Help for Becoming a Better API User

Hi there!

I have been mostly self teaching myself how to use the materials project API but I was wondering if anyone has some examples/tutorials I should be checking out. I have mostly been using the Materials Project YouTube page, some example notebooks, and this forum to learn. I know the workshop is coming up but I don’t know if I want to put down the money (especially considering I already know python and basic API use). Does anyone have any thoughts or suggestions of things I should look into?

Also any tips for a beginner (dos and don’ts)? Like don’t hammer the API with tons of requests.

Thanks so much!

1 Like

You mentioned using the Materials Project YouTube channel, which includes a playlist for the 2019 workshop.

What may not be obvious is that all workshop curriculum material (including reference notebooks for lessons) has been openly developed at For example, a snapshot of the repo for the 2019 workshop is here (git tag v2019).

Because you know Python, one resource for you that embodies best practices and expectations about API use is MP’s pymagen interface to the API. By looking over the source code for pymatgen’s MPRester and running/reading the source code for its tests (these links are pinned to the latest-release v2020.4.29 tree of the pymatgen repo), you can grow to understand a lot about efficient/effective use of the API. For example, the MPRester.query has code to ensure that a query requesting a lot of data is batched into smaller queries both so that MP’s server is less likely to be overloaded and so that you as an end user get a progress bar to predict how long it will take your program to download all that data.

Finally, it’s useful to understand the MP API’s underlying data and query model. There are elements of the API that follow a REST-like model, with different URL routes that pertain to different named resources. Reading about REST APIs in general will help you both with MP’s data and with other REST-like APIs.

However, another powerful component of the MP API – distinct from the REST-like modeling – is near-direct exposure of underlying MongoDB collections. The mapidoc repo helps to explore the JSON model of documents in MP’s materials collection. The MPRester.query method – and corresponding API endpoint – allows you to express queries using the MongoDB filter query language, and to limit what data you require from the API server using MongoDB projections. Thus, learning more about the MongoDB document-oriented query language will help you become a better API user as well.


Thank you so much! This is exactly the guidance I was looking for. I really appreciate the help!

1 Like