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:

curl R Python

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

TODO R code

TODO Python code

Note

This is a general example and will only work on instances that have the fields region, country, and date. Check out the fields and filters page to see information about this instance.

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.

Tip

This is useful if you want to send the query directly from a HTML form. If <form> element has the method attribute set to POST and the enctype attribute set to application/x-www-form-urlencoded (which is the default value), then the <form> element will send the data as URL encoded form data.

Example

This is an HTML snippet that yields such a form:

<form action="https://lapis.genspectrum.org/open/v2/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:

Field to aggregate by: