Using MAPI to retrieve materials' voltages

Hi all!
I was wondering whether the MP API also supports access to battery-related entities like electrodes’ voltages.
Querying with a simple

with MPRester(key) as mpr:
    query = mpr.query(criteria, ['average_voltage'])

does not appear to retrieve any voltage value. Am I simply fetching a wrong string or is the battery analysis tool not available through API?

Hi @acarnevali, the electrodes data is indeed accessible via the API. I would suggest using the new client to get the latest data release. See Materials Project - API.

You can search the data using:

from mp_api import MPRester

with MPRester(key) as mpr:
    docs = mpr.insertion_electrodes.search_electrode_docs(...)

Thank you for your help! Currently though I am getting the following error:

MPRestError: REST query returned with error status code 401 on URL with message:
Response {
  "message":"Invalid authentication credentials"

is there any further authentication required to access these data?
Moreover, in the API docs the “See the InsertionElectrodeDoc schema for a full list of fields returned by this route.” voice is not linked to any insertion electrodes documentation. Where can I find that?
Lastly, I see that this method is limited to 1000 entries per query: how can one retrieve all the data present in the DB?

Edit: the same happens after generating a new API key associated to my account

Hi @acarnevali,

You will need an API key from the new website. Make sure you are using the one from here: Materials Project - Dashboard

There are a couple of ways to see the available fields. One is to print the available_fields property:


The second is to consult the document schema which can be found here: Materials Project API - ReDoc

Specifically, you can look at the fields to project, or you can take a look at the sample data response on the right. If reading code is easier for you, you can also directly take a look at the data model here:

When using the search method, it will by default retrieve all available data in the DB matching a query in 1000 document chunks. This should happen automatically, and will only return less documents if num_chunks is set to a number.

– Jason

Hello Munrojm,
I have tried to retrieve electrodes data with different working ions. I keep getting errors, please you assist me over come this error.
This is the code i used

from mp_api import MPRester
battery_list2 = pd.DataFrame()
with MPRester(“11111111111111111111111”) as mpr:
battery_list = mpr.insertion_electrodes.search_electrode_docs(“Li”, all_fields=True)
battery_list2 = battery_list2.append(battery_list, ignore_index=True)

@mukhtar, can you post the errors you are getting?

This is the error I get. Thank you for your prompt reply.

ValidationError Traceback (most recent call last)
2 battery_list2 = pd.DataFrame()
3 with MPRester(“11111111111111111111111”) as mpr:
----> 4 battery_list = mpr.insertion_electrodes.search_electrode_docs(“Li”, all_fields=True)
5 battery_list2 = battery_list2.append(battery_list, ignore_index=True)
6 battery_list2.head()

~\AppData\Roaming\Python\Python37\site-packages\mp_api\routes\electrodes\ in search_electrode_docs(self, working_ion, formula,
elements, exclude_elements, max_delta_volume, average_voltage, capacity_grav, capacity_vol, energy_grav, energy_vol, fracA_charge,
fracA_discharge, stability_charge, stability_discharge, num_steps, max_voltage_step, sort_fields, num_chunks, chunk_size, all_fields, fields)
109 }
→ 111 return super().search(**query_params)

~\AppData\Roaming\Python\Python37\site-packages\mp_api\core\ in search(self, num_chunks, chunk_size, all_fields, fields, **kwargs)
436 fields=fields,
437 chunk_size=chunk_size,
→ 438 num_chunks=num_chunks,
439 )

~\AppData\Roaming\Python\Python37\site-packages\mp_api\core\ in _get_all_documents(self, query_params, all_fields, fields, chunk_size, num_chunks)
459 query_params[“limit”] = chunk_size
→ 461 results = self._query_resource(query_params, fields=fields,)
463 # if we have all the results in a single page, return directly

~\AppData\Roaming\Python\Python37\site-packages\mp_api\core\ in _query_resource(self, criteria, fields, suburl, use_document_model)
281 # the client does not handle this in a particularly smart way currently
282 if self.document_model and use_document_model:
→ 283 data[“data”] = [self.document_model.parse_obj(d) for d in data[“data”]] # type: ignore
285 return data

~\AppData\Roaming\Python\Python37\site-packages\mp_api\core\ in (.0)
281 # the client does not handle this in a particularly smart way currently
282 if self.document_model and use_document_model:
→ 283 data[“data”] = [self.document_model.parse_obj(d) for d in data[“data”]] # type: ignore
285 return data

~\SoftwaresInstalled\Anaconda\envs\tf1\lib\site-packages\pydantic\main.cp37-win_amd64.pyd in pydantic.main.BaseModel.parse_obj()

~\SoftwaresInstalled\Anaconda\envs\tf1\lib\site-packages\pydantic\main.cp37-win_amd64.pyd in pydantic.main.BaseModel.init()

ValidationError: 1 validation error for InsertionElectrodeDoc
value is not a valid dict (type=type_error.dict)

@mukhtar, it looks like you might have an older version of the API client. Try updating with pip install mp_api --upgrade and re-running.

– Jason

@munrojm , i have updated it now, it still gives the same error.

Please update emmet-core with pip install emmet-core --upgrade.

If you still are getting an error, please post the versions of mp-api and emmet-core you are using.

– Jason

this are the versions.
emmet-core in /usr/local/lib/python3.7/dist-packages (0.21.3)
mp_api in /usr/local/lib/python3.7/dist-packages (0.18.0)

I still face the same error.


Please try updating to emmet-core v0.21.20 and mp-api v0.20.6.

– Jason

Thank you very much Jason. But there is no mp_api v0.20.6 version available
pip install mp_api==0.20.6 ERROR: Could not find a version that satisfies the requirement mp_api==0.20.6 (from versions: 0.2.1, 0.2.2, 0.2.3, 0.3.0, 0.4.0, 0.4.1, 0.5.0, 0.5.1, 0.6.0, 0.6.1, 0.7.0, 0.7.1, 0.8.0, 0.9.0, 0.9.1, 0.10.0, 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.2, 0.11.3, 0.11.4, 0.12.0, 0.12.1, 0.12.2, 0.13.0, 0.14.0, 0.14.1, 0.15.0, 0.15.1, 0.16.0, 0.16.1, 0.16.2, 0.16.3, 0.16.4, 0.16.5, 0.17.0, 0.18.0)

You will need to update your python version.

– Jason