Welcome!

PDBe’s REST API is a programmatic way to obtain information from the PDB. You can access details about sample, experiment, models, compounds, cross-references, publications, quality, assemblies and more.

There are 3 main parts of our programmatic access offerings at PDBe:

Solr-based query system

The Solr-based query system is a powerful option to search for data in the PDB, offering advanced search options across more than 200 fields. 

View the documentation at this URL: www.ebi.ac.uk/pdbe/api/doc/search.html 

Entry-based API

The Entry-based API provides large amounts of data about an individual entry. This API is based on input of PDB or ligand IDs. 

View the documentation at this URL: www.ebi.ac.uk/pdbe/api/doc 

Aggregated API

Our aggregated API provides calls for aggregated data from across all the relevant PDB entries, for example based on entities, Uniprot IDs, residues and more.

View the documentation at this URL: pdbe.org/aggregated-api 

 

Find out more

For more information, visit the following links:

• Frequently asked questions (FAQ)
• Webinars and materials to learn more about PDBe programmatic access
• PDBe API user mailing list

Why?

3D biomacromolecular structures are vital for high-impact scientific work such as basic science, disease research, drug discovery, material design and so on. The Protein Data Bank is a substantial resource of macromolecular structure and continues to expand its holdings thanks to experimental advances. An average entry is more complex than a decade ago in terms of its size and chemical variety. Advanced data-intensive approaches are essential to connect 3D structures to the wider context of biological data and scientific literature. Easy access to interesting bits of structural data is crucial for such integrative analyses.

In order to carry out large-scale data analysis, it is easier to do this directly through the REST API, rather than needing to download all the relevant files. The whole entry file is required for obtaining a tiny detail like the resolution, yet important information like cross-references, chemistry and quality might reside in other files. Furthermore, not all cross-references are found in the archive file and are not kept up-to-date, while there are a number of additional annotations beyond cross references.

We use the API for the PDB and PDBe-KB entry pages

Since our entry pages are powered by the REST API, it is subjected every week to a battery of tests. The data sources underlying the REST API are updated weekly so that the delivered content is up-to-date.

Who else uses the REST API

There are a growing number of software packages that have integrated PDBe REST API calls for quality metrics, cross-references and data visualisation. Furthermore, it is widely used by academic and industry groups to support research efforts.

Outlook

The current set of calls in the REST API is largely shaped by the needs of PDBe services and user feedback. We are open to implementing new calls and features, as well as fixing any bugs. We envision the REST API to be a long-term, stable, well-tested resource for powering traditional and novel applications using 3D structural information. We look forward to hearing from you, and receiving your HTTP requests!

 

FAQs

How do I subscribe to the mailing list?

Send e-mail to  pdbe-api-users-join@ebi.ac.uk. This is a useful channel for us to communicate actively with you about new features, changes, planned downtime, etc.

Where can I find calls and their documentation?

For the entry-based API, you can find it at this URL: www.ebi.ac.uk/pdbe/api/doc 

For the aggregated API, you can find it at this URL: pdbe.org/aggregated-api 

Can I request a new call?

Of course you can. But make sure there is no call which already returns what you need. Send an email to the pdbe-api-user mailing list with details of the call and its intended application.

How do you test the API?

Many PDBe services in production use the live API. So any downtime and most bugs get noticed and fixed quickly. A battery of tests is run weekly for checking correctness and stability.

How do I report a bug?

Please subscribe to the mailing list. Report as much detail as possible, e.g. operating system, programming language used (if any), libraries, call URL, response, http status, etc. We also welcome reports of errors in the documentation.

How many API calls am I allowed?

At present we rely on user restraint and have not set any hard limits. But in future, depending on load on our servers, we may want to implement rate limiting.

How many ids may I include in a POST request?

You can ask for as many as 1000 ids at once.

Why not allow lower-case compound ids?

The Chemical Component Dictionary (CCD) of the PDB defines the ids in upper case. All internal (and most external) data sources have them in upper case.

Where can I find examples?

Code samples to get started can be found here.

How can I stay up to date with new API releases?

Please subscribe to the mailing list. We post information about new calls and updates to existing calls.

Can I make AJAX calls?

Yes, CORS support is activated in our servers so you don’t have to use JSONP.

Can I see an example?

We have prepared Python examples as Jupyter notebooks that you can use as a template.