Skip to main content

REST API

This guide explains how to integrate GWAS Catalog data into scientific pipelines, scripts and web applications, with examples for developers. For help, contact gwas-info@ebi.ac.uk.

🤔 What data can I find in the API?​

The GWAS Catalog REST API provides access to literature-curated top associations and metadata: the same data available through the GWAS Catalog website, selected according to the Catalog's eligibility criteria.

Use the API to find variants linked to a disease, search across traits for a variant, summarise associations within a population group, or identify studies with full-genome-wide summary statistics available to download.

REST API v2 is the only currently supported version of the GWAS Catalog API. V1 was retired in August 2026.

🛠️ Where can I find a technical reference for the API?​

The API reference describes endpoints, schemas, parameters, syntax, definitions and response codes. It also provides a visual, interactive interface for exploring and testing endpoints.

For documentation about the controlled vocabularies and annotations used in the Catalog and API, see:

🚀 Help me get started!​

Pagination​

API responses are paginated to manage performance, scalability and usability. The default page size is 20 records. If a response has more results, follow its next link to retrieve the next page.

Trait searches​

When querying by efo_trait (ontology trait mapping), choose whether results include only data annotated directly with the query term or also data annotated with more specific child traits:

  • Set show_child_traits=false to return only data annotated directly with the query term. For example, a search for “asthma” will not include data annotated with “status asthmaticus”.
  • Set show_child_traits=true to include data annotated with the query term and its child traits. This is the default on GWAS Catalog trait pages.

To identify a wider range of matching traits before querying another endpoint, start with the efo_trait endpoint. A free-text search returns traits whose names include the search term. For example, a search for “COVID-19” can return “COVID-19”, “COVID-19 symptoms measurement”, “long COVID-19”, “response to COVID-19 vaccine” and “time to remission of COVID-19 symptoms”. Trait names are shown here for readability; use the efo_id (for example, MONDO_0004979) where possible for more precise queries. See the ontology documentation for more about trait annotation.

Gene filters​

For association or single-nucleotide polymorphism queries by gene, choose which gene set to use with the extended_geneset parameter:

  • extended_geneset=false uses the genes that a GWAS Catalog variant maps to, or its nearest upstream and downstream genes, according to Ensembl annotation. This matches the annotation shown in the GWAS Catalog website.
  • extended_geneset=true uses an extended set of all Ensembl and RefSeq genes mapping upstream and downstream of each GWAS Catalog variant. This was the annotation used in API v1.

The default is extended_geneset=false.

🧑‍💻 Examples of a few key ways to use the GWAS API​

For hands-on, executable examples, explore the GWAS Catalog Jupyter notebooks. They show how to answer questions such as which variants are associated with a disease, which studies of a trait have full summary statistics available, and which SNP has the strongest effect size for a disease. The notebooks are a useful starting point for new REST API users.

Rate limits​

The API allows up to 100 requests per minute and 15 requests per second per IP address. Requests above either limit are blocked and receive an HTTP 429 Too Many Requests response.

If your client will send many requests, such as when it crawls the full API, set a descriptive User-Agent header. For example, use MyResearchProject/1.0 (contact: name@example.org).

Bulk access

For bulk access, download the GWAS Catalog flat files instead of crawling the API. Flat files provide a more efficient and faster way to retrieve the full dataset.

Summary statistics​

There is currently no API for accessing GWAS Catalog summary statistics. The previously available API was frozen in 2021 and retired in 2026.

Where available, summary statistics can be accessed from individual GWAS Catalog study pages or downloaded from the summary statistics tables.