We are pleased to announce some major improvements to the Resolve V2 API, which is used to programmatically look up DCIDs of knowledge graph entities. Up until today, you could only resolve place types and get limited metadata in the response. Now we’ve added several enhancements that support a much wider range of use cases:

• Support for resolving statistical variables and topics, which you can look up by description
• Additional metadata, such as the confidence scores of the candidate results, available for variables and topics
• Ability to limit results to either variable or topics exclusively by using the typeOf filter
• For Custom Data Commons instances, ability to restrict the results to your own data if desired

Summary of API changes

New resolve parameters

Two new optional parameters are available for the resolve REST endpoint and resolve.fetch Python method:

• resolver, which allows you to choose between places and indicators (variables and topics). If not set, it defaults to places.
• target, which allows Custom Data instance owners to choose the source of the data among custom, base, or custom+base

Examples:

REST: 

https://api.datacommons.org/v2/resolve?key=...&nodes=population&resolver=indicator

Python: 

resolve.fetch(node_ids="population", resolver="indicator")

New Python method

A new Python convenience method, resolve.fetch_indicators, is available. It takes two parameters:

• queries (required)
• target (optional)

Example:

resolve.fetch_indicators(queries="female population over 50")

New response metadata

A new metadata object is returned in the response for indicator resolutions, containing two fields:

• score – the confidence score of the ranking of the candidate in the results
• sentence – the candidate’s description

Example:

"metadata": {
   "score": "0.8982",
   "sentence": "population count"
},

Default property for places

For simple place resolutions by description, you can omit the property (REST) or expression parameter (Python).

Examples:

REST:

https://api.datacommons.org/v2/resolve?key=...&nodes=Georgia

Python:

resolve.fetch(node_ids="Georgia")

Documentation and examples

For full details and examples, see the following pages:

• REST: v2/resolve
• Python: resolve