Query multiple chemical systems

Hi, I am trying to query multiple chemical systems. For example, I want to retrieve all entries for the Fe-Ni and Fe-Cr systems. I first tried the string search using criteria=“Fe-Ni Fe-Cr”, but got the error “Query should not be or”. I also tried the dict search with criteria = {“elements”: {"$or": [{"$all": [“Fe”,“Ni”]}, {"$all": [“Fe”,“Cr”]}]}, “nelements”:2}, but got the error “unknown operator: $or”. Can someone tell me how to get it done correctly? Thanks!

Hi @mathsphy, welcome!

First, I just want to draw to your attention that we have two parallel APIs right now: a newer one under active development and retrieving new data updates, and a legacy one, frozen and no longer receiving data updates.

The table on this page summarizes the difference and is important to review: Materials Project - API

For your query, a few thoughts come to mind:

  • In the new API you might do a query like this:
from mp_api import MPRester

# API key for new API from https://next-gen.materialsproject.org/api
mpr = MPRester(api_key=YOUR_API_KEY)

# for core materials information, this query returns 25 documents
docs = mpr.materials.search_material_docs(chemsys=["Fe-Ni", "Cr-Fe"]) 

# alternatively, if you're interested in properties of the materials too, this summary endpoint 
# includes aggregated information about the material as well, like it's energy above hull
docs = mpr.summary.search_summary_docs(chemsys=["Fe-Ni", "Cr-Fe"]) 

This supports OR style queries by simply giving a list of chemical systems. Note that chemical systems are defined in alphabetical order, e.g. Cr-Fe not Fe-Cr.

Information about this new API is still subject to change until it’s finalized, so for anyone reading this message in the future, please make sure to review our documentation :slight_smile:

  • Only the legacy API supports Mongo-style queries like the one in your example. Supporting arbitrary queries has the potential to scale badly on our servers, so right now we are not supporting them on the new API. However, we are trying to make sure we cover any use cases people need, and to be responsive to feature requests.

  • Finally, the amount of information to retrieve is typically not so large, and sometimes it can be fast enough to query more information than you need and filter down once it’s been retrieved, or, conversely, to do 2–3 different API queries instead of spending time to find the syntax to do just a single query is just the easier path forward. This advice is not appropriate for everyone, and is only true within reasonable limits (eg, if you can do a single API query instead of 1000 separate API queries, it would be much better to do the single query).

Hope this helps! Let us know if you have any follow up questions.


Hi @mkhorton, thank you very much for your reply and suggestions!

1 Like