API Overview

API Overview

The JASPAR RESTful API provides programmatic and human-browsable access to the JASPAR database. This is implemented in Python using the Django REST Framework.

API Versioning

Currently, the JASPAR API is at version 1, being available at https://jaspar2018.genereg.net/api/v1/. New versions will be released here with new URLs and there will be a prior notice before obsoleting any older API version.

Throttling

Our API is using throttling in order to control the rate of requests that clients can make to the API. We allow 25 requests per second from the same IP address, but no limit on the total number of requests.

Please feel free to write to us if you need higher request.

Pagination

To provide a faster response to each request and to prevent larger accidental downloads, the API provides pagination. Users can increase or decrease the number of records per pages by setting page_size. By default page_size=10, which can be increased up to 1000.

https://jaspar2018.genereg.net/api/v1/matrix/?page=1&page_size=25

To jump from one page to another, modify the page parameter:

https://jaspar2018.genereg.net/api/v1/matrix/?page=2

Ordering

This supports simple query parameter controlled ordering of results. The query parameter is named order.

For example, to order matrices by name:

https://jaspar2018.genereg.net/api/v1/matrix/?order=name

The client may also specify reverse order by prefixing the field name with '-', like this:

https://jaspar2018.genereg.net/api/v1/matrix/?order=-name

Multiple orderings may also be specified:

https://jaspar2018.genereg.net/api/v1/matrix/?order=name,version

Output formats

The REST API provides several data renderer types that allow you to return responses with various media types. The query parameter is named format.

Currently, available data formats are json, jsonp, api, yaml, jaspar, transfac, pfm.

For example, to return all the matrices in JSON format:

https://jaspar2018.genereg.net/api/v1/matrix/?format=json

For example, to return PFM values of matrix MA0001.1 in JASPAR format:

https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1/?format=jaspar

The above URL will return this:

>MA0001.1 AGL3
A [  0.00   3.00  79.00  40.00  66.00  48.00  65.00  11.00  65.00   0.00]
C [ 94.00  75.00   4.00   3.00   1.00   2.00   5.00   2.00   3.00   3.00]
G [  1.00   0.00   3.00   4.00   1.00   0.00   5.00   3.00  28.00  88.00]
T [  2.00  19.00  11.00  50.00  29.00  47.00  22.00  81.00   1.00   6.00]

You can set the output format type in three different ways:

  1. By setting ?format=format url parameter. For example:
  2. By adding .format suffix. For example:

  3. By using the Accept headers. For example:

    curl 'https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1' -H 'Accept: application/json'
curl 'https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1' -H 'Accept: application/javascript'
curl 'https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1' -H 'Accept: application/yaml'
curl 'https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1' -H 'Accept: text/html'
curl 'https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1' -H 'Accept: text/jaspar'
curl 'https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1' -H 'Accept: text/transfac'
curl 'https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1' -H 'Accept: text/pfm'
curl 'https://jaspar2018.genereg.net/api/v1/matrix/MA0001.1' -H 'Accept: text/meme'

    If there is a conflict between the Accept headers and the format parameter, the following error message will be returned:

    curl 'https://jaspar2018.genereg.net/api/v1/matrix/?format=jsonp' -H 'Accept: application/json'
{
"detail": "Could not satisfy the request's Accept header"
}

CORS requests

JASPAR API also supports Cross-Origin Resource Sharing (CORS), which enables users to make cross-origin API requests directly from their web application.

Caching

Setting up the cache is very useful to enhance the performance of the API. For this API, we are using Memcached, which is a fast, efficient and entirely memory-based cache server. It is used by sites such as Facebook and Wikipedia to reduce database access and dramatically increase site performance. Memcached runs as a daemon and is allotted a specified amount of RAM. All it does is provide a fast interface for adding, retrieving and deleting data in the cache. All data is stored directly in memory, so there’s no overhead of database or filesystem usage. We are using a Python Memcached binding python-memcached, which is running on localhost (127.0.0.1) port 11211.