API status

  • 3.8.7 Version
  • public Access level

346,560,025,481 genetic associations
50,188 GWAS summary datasets.

  • Available Neo4j status
  • Available ElasticSearch status
  • Available LD reference panel
  • Available PLINK executable
  • Unavailable Cromwell
  • Available Population LD scores and frequencies

Documentation GWAS home page

Overview

This is a RESTful API for programmatic access to the IEU OpenGWAS database. The API is designed to support the following operations:

  • Make available study information about all the GWAS datasets in the database
  • Obtain the top hits from a GWAS, with optional automatic clumping.
  • Find any set of variant-trait associations based on rsid or chromosome:position.
  • Automatically find LD proxies if a variant is missing from a GWAS database.
  • Calculate LD matrices across a set of variants.
  • Phenome-wide association study (PheWAS) - Perform fast lookups of a particular variant across all datasets.
  • Get dbSNP information and annotations on a set of variants.

The API can be used directly in applications, or accessed through convenient packages in R and python. More information on those below. The TwoSampleMR R package, and MR-Base web apps both use this API in order to automatically perform Mendelian randomization for causal inference. The gwasglue R package aims to extend the use of these data to further types of statistical methods. The LD Hub platform also uses the data underlying this database.

Authentication


Methods of authentication:
EndpointUntil 30th April 2024From 1st May 2024
/status, /batchesNoneNone
All other endpointsGoogle OAuth token (optional*), or
JWT (optional*)
(*: only necessary if you want to use private datasets or benefit from higher allowance)		JWT (required)
To be deprecated soon - Token obtained from Google OAuth

The documentation provides a list of endpoints, the parameters they require, descriptions of the data that is returned, and an interactive way to try out each of the endpoints.

The database of GWAS summary data mostly contains public data, however there are some 'private' datasets, which can only be accessed by authorised users.

Authentication is managed using Google OAuth 2.0. In order to authenticate, you will need to generate a 'token' for each session in which private access is required.

The simplest way to obtain an authentication token is to use a browser to authenticate with your gmail account at this link.

The access token can also be obtained using the ieugwasr::get_access_token() function, more information about that here.
Now rolling out - JSON Web Token (JWT) issued by us

From Wednesday 1st May 2024, you need to prove your identity (authenticate) to use our service, even if you are querying a public dataset.

JSON Web Token (JWT) is used for authentication. The token is required for most endpoints. To obtain a token, sign in to the account page. You will be prompted to generate a token, which is valid for 14 days. To use your token, add it into your request header under the key Authorization with value Bearer your_token. Note that there is a whitespace between Bearer and your token.

The API documentation provides a list of endpoints, whether they are protected (require authentication), the parameters and responses, and an interactive way to try out. To try the protected endpoints, click the green 'Authorize' button in API docs and provide your token as instructed.

Transition period (from now until May 2024)

You will still be able to use our service anonymously until 30th April 2024.

All the endpoints can work anonymously, except for one endpoint that we created to help you validate your implementation of the new authentication process. You may want to visit the API docs and find the /user endpoint.
- What will happen without a valid token?
If you just click 'Try it out' then 'Execute', you will get a '401 Unauthorized' error.
- What if I have a valid token?
If you focus on the upper right corner of the /user area, you will see a lock icon. Click the lock icon and you will find 'token_jwt' as available authorizations. Follow the instruction, click 'Authorize', and finally try to execute on the /user endpoint again. This time you will get '200 OK' and you can see your user information in the response body.
- Is there any other errors?
Yes. You may see other errors (e.g. if you go beyond the rate limit you will get the '429 Too Many Requests' error), so you should only use the 200 status code as the indicator of success, although you may also want to check the response body.

Allowance and cost

Allowance (free credits)

As part of our fair use policy, users will be given allowance for the cost of the requests they make in each time span. The allowance is provided free of charge.

The allowance is reset periodically. The clock starts at your first request. E.g. if the allowance is "1000 per 10 minutes" and you made your first request at 09:41, your allowance will be reset to 1000 at 09:51. Your real-time allowance information is available on your account page, or in the response header (X-Allowance-* and Retry-After) of every request, except for those endpoints of which the cost is 0.

Note: University of Bristol users (who signed in using Microsoft, GitHub or email verification, as long as the email address on your OpenGWAS profile ends with @bristol.ac.uk) will be given higher allowance than displayed below. Please check your account page for details.

Method of most recent sign-inAllowance (free credits)
Microsoft100000 per 10 minutes
GitHub100000 per 10 minutes
Email verification20000 per 10 minutes
Anonymous0 per 10 minutes
Cost (per request)

EndpointCost per requestCondition
/status, /batches, /users0 (no cost, but still subject to fair-use policy)
/gwasinfo1
50		1 ≤ Nid ≤ 100
100 < Nid or no id is specified
/associationsmax(Nid, Nvariant)
max(Nid, Nvariant) × 5
proxies = 1
/tophitsNid
Nid × 10
Nid × 30		clump = 1 (use preclumped data)
clump = 0 (return all records)
clump = 1 (requires new clumping)
/ld/clumping
/ld/matrix
/ld/reflookup		Nrsid × 10
20
2
/phewas(Nvariant_rsid + Nvariant_chrpos) × 75 + Nvariant_cprange × 750
/variants
/variants/afl2/snplist		1
10

Related tools

For ease of use we have developed two packages which are solely designed to create easy interfaces to the API endpoints:

  • The ieugwasr R package [link]
  • The ieugwaspy python package [link]

The following packages also connect to these data:

  • The TwoSampleMR R package automatically performs Mendelian randomization on the data accessed through the API [link]
  • The gwasglue R packages connects the data to several other analytical tools related to e.g. colocalisation, fine mapping, etc [link]
  • The https://gwas.mrcieu.ac.uk page provides an interactive way to browse through the available datasets.
  • The MR-Base web app uses the underlying data for basic interactive [link]