---
layout: default
title: Resolve entities
nav_order: 4
parent: REST (V2)
grand_parent: API - Query data programmatically
published: true
include_scripts:
- /assets/js/syntax_highlighting.js
- /assets/js/api-doc-tabs.js
---
{: .no_toc}
# /v2/resolve
* TOC
{:toc}
Each entity in Data Commons has an associated `DCID` which is used to refer to it
in other API calls or programs. To make any other API calls, you must know the DCIDs of the entities or variables you want to query. The Resolve API searches for an entry in the Data Commons knowledge graph based on specified properties and returns the DCIDs of matches.
To fetch more data for the returned candidates, including linked nodes, you can then call Node API.
## Request
### Query parameters
| Name | Type | Description |
|---------------|-------|----------------|
| key Required | string | Your API key. See the [section on authentication](/api/rest/v2/index.html#authentication) for details. |
| nodes Required | list of strings | A list of terms that identify each node to search for, such as their names. A single string can contain spaces and commas. If the `resolver` parameter is not set to `indicator`, the value must exactly match the actual property value of the entity. |
| resolver Optional | string literal | The only currently accepted option is `indicator`, which resolves statistical variables and topics. By default, queries resolve all other types of nodes. |
| property Optional | string | An expression that describes the identifier used in the 'nodes' parameter. You can use any valid incoming property (edge) on any type of node. You may use a 'typeOf' filter only for place resolutions using the special synthetic properties '<-geoCoordinate' or '<-description'. If this parameter is not specified, the default is '<-description'. For all other place-related resolutions, this parameter is required. Each expression must end with '->dcid'.
Note: For Custom Data Commons instances, when 'resolver=indicator' is not specified, only place resolutions are supported, with a subset of properties. See [Supported place properties for Custom Data Commons](#placetypes) for a list of these. |
| target Optional | string literal | Only relevant for Custom Data Commons: specifies the Data Commons instance(s) whose data should be queried. Supported options are: `custom_only` `base_only` `base_and_custom`. If not specified, the default is `base_and_custom`. |
{: .doc-table }
> **Note:** For places, this endpoint relies on name-based geocoding, which may return imprecise results. One common pattern is ambiguous place names, that are the same in different countries, states, etc. For example, there is at least one popular city called "Cambridge" in both the UK and USA. Thus, for more precise results, provide as much context in the description as possible. For example, to resolve Cambridge in USA, pass "Cambridge, MA, USA" if you can. For indicators, the endpoint returns all possible results that match the query. To limit results, use more precise query terms.
## Response
The response contains all the candidates that match the query.
When the `resolver` option is not specified, the response looks like:
{: .response-signature .scroll}
### Response fields
| Name | Type | Description |
|-------------|--------|-------------------------------------|
| node | string | The property value or description provided. |
| candidates | list of objects | A list of candidate nodes matching the description you provided. Each candidate contains a DCID and (optionally) metadata and type. |
| dcid | string | The DCID of the candidate node. |
| dominantType | string | Optional field which, when present, disambiguates between multiple results. Only returned when `resolver` is set to `place` (the default). |
| metadata.score | float | The confidence score for the result, used to rank multiple results. Only returned when `resolver` is set to `indicator`. |
| metadata.sentence | string | The matching substring contained in the node's name or description. Only returned when `resolver` is set to `indicator`. |
| typeOf | list of strings | The type(s) of the result. Currently supports only `StatisticalVariable` and `Topic`. |
{: .doc-table}
## Examples
### Example 1: Find the DCID of a place by another known ID
This queries for the DCID of a place by its Wikidata ID. This property is represented in the graph by [`wikidataId`](https://datacommons.org/browser/wikidataId){: target="_blank"}.
Parameters:
{: .example-box-title}
```bash
nodes: "Q30"
property: "<-wikidataId->dcid"
```
GET Request:
{: .example-box-title}
```bash
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Q30&property=%3C-wikidataId-%3Edcid'
```
POST Request:
{: .example-box-title}
```bash
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["Q30"], "property": "<-wikidataId->dcid"}'
```
Response:
{: .example-box-title}
```json
{
"entities" : [
{
"node" : "Q30",
"candidates" : [
{
"dcid" : "country/USA"
}
],
}
]
}
```
{: .example-box-content .scroll}
{: #geocoordinate}
### Example 2: Find the DCID of a place by coordinates
This queries for the DCID of "Mountain View" by its coordinates. This is most often represented by the [`latitude`](https://datacommons.org/browser/latitude){: target="_blank"} and [`longitude`](https://datacommons.org/browser/longitude){: target="_blank"} properties on a node. Since the API only supports querying a single property, use the synthetic `geoCoordinate` property. To specify the latitude and longitude, use the `#` sign to separate both values. This returns all the places in the graph that contains the coordinate.
Parameters:
{: .example-box-title}
```bash
nodes: "37.42#-122.08"
property: "<-geoCoordinate->dcid"
```
GET Request:
{: .example-box-title}
```bash
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=37.42%23-122.08&property=%3C-geoCoordinate-%3Edcid'
```
POST Request:
{: .example-box-title}
```bash
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["37.42#-122.08"], "property": "<-geoCoordinate->dcid"}'
```
{: .example-box-content .scroll}
Response:
{: .example-box-title}
```json
{
"entities" : [
{
"node" : "37.42#-122.08",
"candidates" : [
{
"dcid" : "geoId/0649670",
"dominantType" : "City"
},
{
"dcid" : "geoId/06085",
"dominantType" : "County"
},
{
"dcid" : "geoId/06",
"dominantType" : "State"
},
{
"dcid" : "country/USA",
"dominantType" : "Country"
},
{
"dcid" : "geoId/06085504601",
"dominantType" : "CensusTract"
},
{
"dcid" : "geoId/060855046011",
"dominantType" : "CensusBlockGroup"
},
{
"dcid" : "geoId/0608592830",
"dominantType" : "CensusCountyDivision"
},
{
"dcid" : "geoId/0618",
"dominantType" : "CongressionalDistrict"
},
{
"dcid" : "geoId/sch0626280",
"dominantType" : "SchoolDistrict"
},
{
"dcid" : "ipcc_50/37.25_-122.25_USA",
"dominantType" : "IPCCPlace_50"
},
{
"dcid" : "zip/94043",
"dominantType" : "CensusZipCodeTabulationArea"
}
],
}
]
}
```
{: .example-box-content .scroll}
### Example 3: Find the DCID of a place by name
This queries for the DCID of "Georgia". Notice that specifying `Georgia` without a type filter returns all possible DCIDs with the same name: the state of Georgia in USA ([geoId/13](https://datacommons.org/browser/geoId/13){: target="_blank"}), the country Georgia ([country/GEO](https://datacommons.org/browser/country/GEO){: target="_blank"}) and the city Georgia in the US state of Vermont ([geoId/5027700](https://datacommons.org/browser/geoId/5027700){: target="_blank"}).
Note that the expression `<-description->dcid` is set implicitly.
Parameters:
{: .example-box-title}
```bash
nodes: "Georgia"
```
GET Request:
{: .example-box-title}
```bash
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Georgia'
```
POST Request:
{: .example-box-title}
```bash
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["Georgia"]}'
```
Response:
{: .example-box-title}
```json
{
"entities" : [
{
"node" : "Georgia",
"candidates" : [
{
"dcid" : "geoId/13"
},
{
"dcid" : "country/GEO"
},
{
"dcid" : "geoId/5027700"
}
],
}
]
}
```
{: .example-box-content .scroll}
### Example 4: Find the DCID of a place by name, with a type filter
This queries for the DCID of "Georgia". Unlike in the previous example, here
we also specify its type using a filter and only get one place in the response.
Parameters:
{: .example-box-title}
```bash
nodes: "Georgia"
property: "<-description{typeOf:State}->dcid"
```
GET Request:
{: .example-box-title}
```bash
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Georgia&property=%3C-description%7BtypeOf:State%7D-%3Edcid'
```
POST Request:
{: .example-box-title}
```bash
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["Georgia"], "property": "<-description{typeOf:State}->dcid"}'
```
Response:
{: .example-box-title}
```json
{
"entities" : [
{
"node" : "Georgia",
"candidates" : [
{
"dcid" : "geoId/13"
}
],
}
]
}
```
{: .example-box-content .scroll}
### Example 5: Find the DCID of multiple places by name, with a type filter
This queries for the DCIDs of "Mountain View" and "New York City".
Parameters:
{: .example-box-title}
```bash
nodes: "Mountain View, CA", "New York City"
property: "<-description{typeOf:City}->dcid"
```
GET Request:
{: .example-box-title}
```bash
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Mountain%20View,%20CA&nodes=New%20York%20City&property=%3C-description%7BtypeOf:City%7D-%3Edcid'
```
{: .example-box-content .scroll}
POST Request:
{: .example-box-title}
```bash
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["Mountain View, CA", "New York City"], "property": "<-description{typeOf:City}->dcid"}'
```
{: .example-box-content .scroll}
Response:
{: .example-box-title}
```json
{
"entities" : [
{
"node" : "Mountain View, CA",
"candidates" : [
{
"dcid" : "geoId/0649670"
},
{
"dcid" : "geoId/0649651"
}
],
},
{
"node" : "New York City",
"candidates" : [
{
"dcid" : "geoId/3651000"
}
],
}
]
}
```
{: .example-box-content .scroll}
### Example 6: Find the DCID of a statistical variable
This queries datacommons.org for statistical variables containing the term "population".
Parameters:
{: .example-box-title}
```bash
nodes: "population"
resolver: "indicator"
```
GET Request:
{: .example-box-title}
```bash
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=population&resolver=indicator'
```
{: .example-box-content .scroll}
POST Request:
{: .example-box-title}
```bash
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["population"], "resolver": "indicator"}'
```
{: .example-box-content .scroll}
Response:
{: .example-box-title}
(truncated)
```jsonc
{
"entities": [
{
"node": "population",
"candidates": [
{
"dcid": "Count_Person",
"metadata": {
"score": "0.8982",
"sentence": "population count"
},
"typeOf": [
"StatisticalVariable"
]
},
{
"dcid": "IncrementalCount_Person",
"metadata": {
"sentence": "population change",
"score": "0.8723"
},
"typeOf": [
"StatisticalVariable"
]
},
{
"dcid": "Count_Person_PerArea",
"metadata": {
"score": "0.8354",
"sentence": "Population Density"
},
"typeOf": [
"StatisticalVariable"
]
},
{
"dcid": "dc/topic/Demographics",
"metadata": {
"score": "0.8211",
"sentence": "Demographics"
},
"typeOf": [
"Topic"
]
},
{
// ...
]}]}
```
{: .example-box-content .scroll}
### Example 7: Find the DCID of a non-place entity using its name
This example looks up the DCID of a statistical variable group by its name.
Parameters:
{: .example-box-title}
```bash
nodes: "Sustainable Development Goals"
property: "<-name"
```
GET Request:
{: .example-box-title}
```bash
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Sustainable%20Development%20Goals&property=%3C-name-%3Edcid'
```
{: .example-box-content .scroll}
POST Request:
{: .example-box-title}
```bash
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["Sustainable Development Goals"], "property": "<-name->dcid"}'
```
{: .example-box-content .scroll}
Response:
{: .example-box-title}
```jsonc
{
"entities": [
{
"node": "Sustainable Development Goals",
"candidates": [
{
"dcid": "WHO/g/SustainableDevelopmentGoals"
},
{
"dcid": "dc/g/SDG"
},
{
"dcid": "dc/topic/sdg"
}
]
}
]
}
```
{: .example-box-content .scroll}
### Example 8: Find the DCID of an entity using another field
This example looks up the DCID of a provenance by its URL.
Parameters:
{: .example-box-title}
```bash
nodes: "https://unstats.un.org/sdgs/dataportal"
property: "url"
```
GET Request:
{: .example-box-title}
```bash
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=https://unstats.un.org/sdgs/dataportal&property=%3C-url-%3Edcid'
```
{: .example-box-content .scroll}
POST Request:
{: .example-box-title}
```bash
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["https://unstats.un.org/sdgs/dataportal"], "property": "<-url->dcid"}'
```
{: .example-box-content .scroll}
Response:
{: .example-box-title}
```jsonc
{
"entities": [
{
"node": "https://unstats.un.org/sdgs/dataportal",
"candidates": [
{
"dcid": "dc/base/UN_SDG"
},
{
"dcid": "dc/d/UnitedNationsUn_SdgIndicatorsDatabase"
}
]
}
]
}
```
{: .example-box-content .scroll}
{: #placetypes}
## Supported place properties for Custom Data Commons
The following is a selection of properties that are supported as the `property` parameter for place resolutions:
| Property label | Description | Examples |
|---------------|-------------|---------|
| `description` | Resolve by description or name. Note that a `description` field is not necessarily present in the knowledge graph for all entities. It is a synthetic property that Data Commons uses to check various name-related fields, such as `name`. You may optionally specify a [`typeOf` filter](/api/rest/v2/index.html#filters) with this property. | `Berlin`, `Berlin, Germany`, `India`|
| `geoCoordinate` | Resolve by a synthesis of [`latitude` and `longitude`](https://datacommons.org/browser/GeoCoordinates){: target="_blank"} properties. This is a synthetic ID assigned by Data Commons. You may optionally specify a [`typeOf` filter](/api/rest/v2/index.html#filters) with this property. | `52.516666666667#-13.383333333333` |
| `wikidataId` | Resolve by [Wikidata ID](https://www.wikidata.org/wiki/Wikidata:Identifiers){: target="_blank"} | `Q64`, `Q668` |
| `unDataCode` | Resolve by the code used in UN-curated datasets. | `undata-geo:C11200007`, `undata-geo:G00001380` |
| `isoCode` | Resolve by ISO 2-letter location code. | `DE-BE`, `IN` |
| `nutsCode`| Resolve by the [NUTS](https://en.wikipedia.org/wiki/Nomenclature_of_Territorial_Units_for_Statistics){: target="_blank"} European Union location code. | `DE3` |
Several region-specific codes are also supported:
* `lgdCode` (India)
* `udiseCode` (India)