Skip to content

Request methods: GET and POST

LAPIS supports queries via GET and POST requests. GET requests encode the query in the URL, offering a simple, shareable format ideal for direct browser access. Most features are supported with GET requests. POST requests requires formatting the query as a JSON and send it in the request body. They support a few advanced queries that are not possible with GET requests. They are ideal if you want to make requests programmatically.

Example

As an example, let’s query the number of sequences per country and date from Africa and receive the data as a CSV file. Hereby, we have to use the /sample/aggregated and set the region parameter to “Africa”, the fields parameter to “country” and “date”, and the dataFormat parameter to “csv”. With GET, multiple values for one parameter are separated by comma. The query URL looks as follows, and you can open it in your browser:

[URL to LAPIS instance]/sample/aggregated?fields=country,date&region=Africa&dataFormat=tsv

Using POST, we have to write the query as a JSON:

{
"fields": ["country", "date"],
"region": "Africa",
"dataFormat": "csv"
}

The JSON will be sent to /sample/aggregated and the Content-Type-header must be set to application/json. Here are example code for doing it with curl and from R and Python:

Terminal window
curl -X POST [URL to LAPIS instance]/sample/aggregated \
-H 'Content-Type: application/json' \
-d '{"fields":["country", "date"],"region":"Africa","dataFormat":"csv"}'

URL Encoded Form Data

LAPIS also supports URL encoded form data for POST requests. The content type must be set to application/x-www-form-urlencoded and the query must be encoded as a query string.

Example

This is an HTML snippet that yields such a form:

<form action="https://s1.int.genspectrum.org/open/sample/aggregated" method="POST">
    <label>
        Field to aggregate by:
        <input type="text" name="fields" value="primaryKey" />
    </label>
    <input type="hidden" name="downloadAsFile" value="true" />
    <input type="submit" value="Submit" />
</form>

This is the rendered HTML snippet. Click on submit send a request to this LAPIS instance: