Getting Started with the NIAGADS-OA API
This guide explains how to construct and execute API requests and interpret responses.
The NIAGADS-OA API establishes a simple framework for sharing and integration of NIAGADS datasets and annotated gene and variant records into analysis pipelines. Use of the API requires either a (command line) tool or requests library that supports the HTTP protocol to transfer data, permitting large-scale programmatic access independent of any specific platform or programming language.
Contribute:
Interested in helping us improve? Check out our GitHub repository to get started! From feature suggestions to code-wrappers to bug reports, all contributions are welcome.
Quick start
Check out the OpenAPI documentation to browse the full, technical specification of API operations.
The NIAGADS OA-API is under development:
Endpoints are subject to change and there may be intermittent outages. Stable release of the full API is expected for September, 2025.
Tools and Libraries
Third-party tools can be used for communicating with the API and for exploring JSON responses. These include:
| Tool | Type |
|---|---|
| curl | command line |
| HTTPie | command line // desktop (Windows) // web app |
| Google Chrome | web browser |
| Mozilla Firefox | web browser |
| Safari | web browser (Mac) |
As well as any programming language package that supports the HTTP protocol, such as:
| Package | Language |
|---|---|
| requests | Python |
| aiohttp* | Python |
| request | R |
| httr2* | R |
| Faraday | ruby |
| net/http | go |
| java.net.http | Java |
| Fetch API | Javascript |
| HTTP::Tiny | Perl |
| LWP::UserAgent | Perl |
*recommended
API Endpoints
Communicating with the NIAGADS Open Access API involves making calls to API endpoints. Each endpoint represents both the resource being queried and specific API functionality.
Request URL
The HTTP URL that corresponds to the latest version of an API endpoint
is:
https://api.niagads.org/<resource>/<operation>
In the request URL, <resource> is the name of the NIAGADS knowledge base and <operation> is
the type of request being made to the API.
Other Versions:
The HTTP URL of an endpoint corresponding to a specific major version of the
API is https://api.niagads.org/v<version>/<resource>/<operation>,
whre <version> is the NIAGADS-OA API major version.
Resources
Allowable values for <resource> are summarized below:
| Resource | Status | Knoweldge Base |
|---|---|---|
| genomics | under development | GenomicsDB |
| filer | in production | FILER |
| advp | planned | ADVP |
| all | planned | search across all Open Access Resources |
Operations
Operations define particular functions or services provided by the API.
Allowable values for <operation> are as follows:
| Operation | Type | Description |
|---|---|---|
| status | Status | Get API description and versioning information |
| record | Entity Lookup | Retrieve entity nomenclature, metadata, or annotations by ID |
| search | Search | Find entities matching search criteria |
| data | Search and Data Retrieval | Retrieve data or annotations matching search criteria |
| service | Data Retrieval | Retrieve data formatted for input to NIAGADS visualization tools or services |
| dictionary | Search and Data Retrieval | Search or retrieve controlled vocabularies and ontologies |
Entities
record operations are further qualified by the entity type being queried.
All entities are assigned a unique stable identifier (ID). These are consistent across all NIAGADS Open Access
resources and are stored in a record's id property.
The HTTP URL for retrieving the record for a specific entity is:
https://api.niagads.org/<resource>/record/<entity>/<id>
The NIAGADS Open Access API supports queries for the following entities:
| Entity | Record Contents | Description | Identifier | Resource |
|---|---|---|---|---|
| gene | annotations, genetic associations | Ensembl genes | Ensembl ID | genomics, advp |
| variant | annotations, genetic associations | SNVs, short INDELS, SVs | chr:pos:ref:alt, structural variant ID | genomics, advp |
| region | overlapping genomic features, data summaries | arbitrary genomic regions | chr:pos:start-end | genomics |
| track | metadata | data tracks | NG[unique alpha-numeric code] | genomics, filer |
| collection | metadata | sets of related entities | human-readable string | genomics, filer |
Alternative Identifiers:
The NIAGADS-OA API will also accept industry standard alternative identifiers, such as refSNP ID for variants, and official symbols, and Entrez (NCBI Gene) IDs for genes. However, these alternatives may not map unambiguously to NIAGADS-OA entities.
Rate Limits
Coming soon:
More information about rate limits on API queries coming soon.
API Responses
The NIAGADS Open Access API uses JSON as its standard response format, although some endpoints can also return
plain text results (formatted as tab-delimited TEXT, YAML, BED, VCF) by setting a format parameter.
Want XML?:
Make a feature request on GitHub!
JSON Response Format
The following fields are included in all successful, non-service API responses. Responses to service routes
will vary depending on their purpose.
| Field | Type | Description |
|---|---|---|
| data | array | query result |
| request | RequestDataModel | details about the originating request |
| pagination | PaginationDataModel (optional) | pagination status, if the result is paged |
| message | array (optional) | warning or info message(s) qualifying the response |
Data
Query results are found in the data field in the API response. It will always be an array; even for single record lookups. However the schema for individual elements in the dataarray will vary depending on the entity or data type being queried.
More information about types of data responses coming soon:
Full JSON schemas are availble in the Open API documentation.
Request
The request field in the response lists the details of the user request.
| Field | Type | Description |
|---|---|---|
| request_id | string | unique request identifier |
| endpoint | string | queried endpoint |
| parameters | object | request path and query parameters, includes unspecified defaults |
Pagination
Many NIAGADS-OA API queries can return large quantities of structured data, all results are paged, with a maximum of 5000 data points returned per page. The pagination field returns the details of the result size and current page.
| Field | Type | Description |
|---|---|---|
| page | integer | if result is paged, indicates the current page of the result; defaults to 1 |
| total_num_pages | integer | if the result is paged, reports total number of pages in the full result set (response); defaults to 1 |
| paged_num_records | integer (optional) | number of records in the current paged result set (response) |
| total_num_records | integer (optional) | total number of records in the full result set (response) |
Status Codes
API responses include a HTTP status code indicating whether the request was successfully completed.
| Status Code | Type | Description |
|---|---|---|
| 200 OK | Success | successful response |
| 404 Not Found | Client Error | record not found |
| 422 Unprocessable Content | Client Error | parameter validation error |
| 429 Too Many Requests | Client Error | too many requests in a given amount of time, exceeding rate limits |
| 500 Internal Server Error | Server Error | runtime error generating a request response |
| 503 Service Unavailable | Server Error | system or database error |