The GWAS Catalog REST API v2 is now available, providing a redesigned way to access curated GWAS Catalog data programmatically.

The API has been redesigned based on user feedback. It provides simpler querying, additional endpoints, richer filtering, ontology-aware searches and access to more Catalog data.

If you currently use the v1 API in scripts, pipelines or applications, this post explains the main differences and what you should review when migrating.

Why a new API?

The GWAS Catalog has grown considerably since the original REST API was developed. V1 provides access to studies, associations, variants and traits, but its design increasingly made complex queries difficult.

V2 takes a different approach. Resources can be queried directly using filters, and additional entities such as publications, genes and ancestries have their own endpoints. The redesign is intended to provide a more robust and scalable API while making complex queries easier to construct.

The API remains focused on the Catalog’s literature-curated top associations and associated metadata. A separate redevelopment is underway for API access to the full genome-wide summary-statistics collection.

At a glance: legacy v1 compared with recommended v2

The v1 column is included only to help existing users find and replace legacy code. For new scripts, pipelines and applications, use v2.

One of the most significant changes is how queries are constructed.

Conceptually, a v1 query might look like this:

/gwas/rest/api/associations/search/findByRsId?rsId=rs123

In v2, search criteria are supplied as filters on the resource:

/gwas/rest/api/v2/associations?rs_id=rs123

The same principle applies across the API. Instead of learning which findBy... endpoint corresponds to a particular query, users can start with the resource they want and filter it. This also makes the API better suited to more complex queries involving multiple criteria.

More ways to filter studies

V1 already provides several ways to find studies, including by PubMed ID, Catalog accession, disease trait, EFO trait and availability of full p-value data. V2 expands the available filtering substantially.

Study searches can include information such as:

• pubmed_id
• disease_trait
• efo_trait
• efo_id
• accession_id
• cohort
• ancestral_group
• mapped_gene

V2 also provides additional study properties, pagination and sorting. Questions that previously required several requests, additional processing or another Catalog data source can increasingly be expressed directly as API queries.

The v2 release also exposes additional data including cohorts, background traits and fuller free-text sample descriptions.

More first-class resources

V1 is centred primarily around four major resources: studies, associations, SNPs and EFO traits.

For example, publication information and ancestry information are contained within the study representation. A v1 study includes publication metadata alongside an array of ancestry records.

V2 exposes more concepts as resources in their own right. These include publications, genes and ancestries, alongside studies, associations, variants and EFO traits.

For example:

/gwas/rest/api/v2/publications
/gwas/rest/api/v2/genes
/gwas/rest/api/v2/studies/{accession_id}/ancestries

This makes it easier to start a query from the entity relevant to your analysis rather than retrieving another resource simply because the information happens to be embedded within it.

Better ontology-aware trait searches

GWAS Catalog traits are mapped to ontology terms, allowing related phenotypes to be represented consistently. V2 can use that ontology hierarchy when performing searches.

When querying by an EFO trait, users can choose between retrieving records annotated directly with the requested trait or also retrieving records annotated with more specific child traits. For example, a query for asthma can either return only records mapped directly to asthma, or additionally include more specific concepts such as status asthmaticus.

This behaviour is controlled using the child-trait search option:

show_child_traits=false

This returns direct annotations only. To include descendant traits, use:

show_child_traits=true

For precise queries, using an ontology identifier such as MONDO_0004979 rather than a text trait name is recommended.

An important change to gene searches

Users migrating gene-based queries should pay particular attention to the definition of the gene set.

V2 provides two definitions of the gene set associated with Catalog variants.

With extended_geneset=false, the API uses genes to which the variant maps, together with the nearest upstream and downstream genes according to Ensembl annotation. This corresponds to the annotation displayed by the current GWAS Catalog web interface.

For example:

https://www.ebi.ac.uk/gwas/rest/api/v2/associations?mapped_gene=HBB&page=0&size=20

With extended_geneset=true, the API uses the broader set of Ensembl and RefSeq genes mapping upstream and downstream of each variant:

https://www.ebi.ac.uk/gwas/rest/api/v2/associations?mapped_gene=HBB&extended_geneset=true&page=0&size=20

The extended gene set corresponds to the annotation used by the v1 API. V2 defaults to the first option to avoid confusing discrepancies with search-page results unless the broader set is intentionally requested.

Therefore, simply recreating a v1 gene query in v2 may not produce the same results. If reproducing v1 gene-query behaviour is important to your analysis, use extended_geneset=true when supported by the endpoint.

Changes to variants

The naming of the SNP resource has also been modernised.

V1 uses /singleNucleotidePolymorphisms and identifies individual SNPs using an rsID. The SNP representation includes genomic locations, functional class and genomic contexts, with links to associated studies and associations.

V2 retains variant and rsID-based querying, but uses the redesigned v2 resource structure and supports filters including rsID, genomic location, PubMed ID, chromosome and mapped gene.

Update both the endpoint URLs and any code that depends on the structure of v1 SNP responses.

Changes to response handling and projections

V1 is explicitly a hypermedia API using HAL. Responses contain _links, and the v1 documentation advises users to follow these links instead of constructing URLs themselves. Collections additionally place records under _embedded.

V1 also makes extensive use of projections, including convenience representations such as associationByStudy, associationBySnp and associationByEfoTrait.

V2 instead provides explicitly documented resources, filters and response schemas through its OpenAPI reference. For applications built around v1, migration involves more than changing request URLs. Code that parses v1 HAL responses or depends on projections should also be reviewed.

Pagination and API usage

Both versions paginate large result sets. V1 returns 20 records by default and documents page and size, with up to 500 records in a single request.

V2 also defaults to 20 records per page. Applications retrieving complete result sets should follow the next links returned by the API rather than assuming that the first response contains every result.

V2 additionally has a rate limit of 15 queries per second. When this is exceeded, subsequent calls are slowed. Pipelines making many requests should account for both pagination and throttling.

More Catalog data through the API

The redesign is not purely technical. V2 exposes data that was previously unavailable through the API or required users to obtain it through the GWAS Catalog website and downloads.

This includes:

New endpoints for publications, genes, genomic contexts and ancestries also allow previously complicated queries to be performed more directly. The result is an API that more closely represents the breadth of information now available within the Catalog.

What do I need to change?

Before you switch over, check these nine things:

If you maintain a pipeline or application using v1, migration should be treated as a small API upgrade project, not just a URL substitution.

In particular, check the following:

1. Endpoint URLs: move requests from /gwas/rest/api/... to the appropriate /gwas/rest/api/v2/... resource.
2. Search calls: replace /search/findBy... endpoints with v2 query parameters.
3. Parameter names: many v2 parameters use names such as pubmed_id, accession_id, efo_trait and mapped_gene.
4. Response parsing: do not assume v1 HAL _embedded, _links or projection structures will be present in the same form.
5. Gene searches: consider extended_geneset=true if you need behaviour equivalent to v1.
6. Trait searches: decide whether descendant ontology traits should be included.
7. Pagination: ensure your application follows paginated results.
8. Request rates: keep the documented 15-query-per-second limit in mind.
9. Data model: consider whether new resources such as publications, genes or ancestries provide a simpler way to perform queries that previously started from studies or SNPs.

GWAS Catalog REST API v2 documentation

Read the GWAS Catalog API documentation for the interactive reference, endpoints, schemas, parameters and syntax.