/v2/resolve

Request
- Query parameters
- Supported place properties
Response
- Response fields
Examples

Each entity in Data Commons has an associated DCID which is used to refer to it in other API calls or programs. An important step for a Data Commons developer is to identify the DCIDs of entities they care about. This API searches for an entry in the Data Commons knowledge graph based on certain properties and returns the DCIDs of matches.

You can resolve place entities by name/description, Wikidata ID, geo coordinates, and several other place codes. You can resolve statistical variables and topics by a substring of the name/description.

To fetch more data for the returned candidates, including linked nodes, you can then call Node API.

Request

https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=IDENTIFIER_LIST&resolver=RESOLUTION_TYPE&property=EXPRESSION&target=INSTANCE

URL: https://api.datacommons.org/v2/resolve Header: X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI JSON data: { "nodes": [ "NODE_IDENTIFIER_1", "NODE_IDENTIFIER_2", ... ], "resolver": "RESOLUTION_TYPE", "property": "EXPRESSION", "target": "INSTANCE" }

Query parameters

Name	Type	Description
key Required	string	Your API key. See the section on 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.
resolver Optional	string literal	Currently accepted options are `place` (the default) and `indicator`, which resolves statistical variables. If not specified, the default is `place`.
property Optional	string	An expression that describes the identifier used in the `nodes` parameter. See Supported place properties for a list of property types you can specify for place resolutions. If not specified, the default is `<-description`. For all other place-related resolutions, this parameter is required. Each expression must end with `->dcid`.
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`.

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.

Supported place properties

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 with this property.	`Berlin`, `Berlin, Germany`, `India`
`geoCoordinate`	Resolve by a synthesis of `latitude` and `longitude` properties. This is a synthetic ID assigned by Data Commons. You may optionally specify a `typeOf` filter with this property.	`52.516666666667#-13.383333333333`
`wikidataId`	Resolve by Wikidata ID	`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 European Union location code.	`DE3`

Several region-specific codes are also supported:

lgdCode (India)
udiseCode (India)

Response

The response contains all the candidates that match the query.

When the resolver option is set to place (the default), the response looks like:

{
  "entities": [
    {
      "node": "NODE_1",
      "candidates": [
        {
          "dcid": "DCID_1",
          "dominantType": "TYPE_OF_DCID_1"
        },
        {
          "dcid": "DCID_2",
          "dominantType": "TYPE_OF_DCID_2"
        },
      ]
    },
    {
      "node": "NODE_2",
      "candidates": [
        {
          "dcid": "DCID_3",
          "dominantType": "TYPE_OF_DCID_3"
        },
      ]
    },
    ...
  ]
}

When the resolver option is set to indicator, the response looks like:

{
  "entities": [
    {
      "node": "NODE_1",
      "candidates": [
        {
          "dcid": "DCID_1",
          "metadata": {
            "score": "CONFIDENCE_SCORE",
            "sentence": "STATVAR_DESCRIPTION"
          },
          "typeOf": [
            "TYPE_OF_DCID_1"
          ]
        },
         {
          "dcid": "DCID_2",
          "metadata": {
            "score": "CONFIDENCE_SCORE",
            "sentence": "STATVAR_DESCRIPTION"
          },
          "typeOf": [
            "TYPE_OF_DCID_2"
          ]
        },
      ]
    },
    {
      "node": "NODE_2",
      "candidates": [
        {
          "dcid": "DCID_3",
          "metadata": {
            "score": "CONFIDENCE_SCORE",
            "sentence": "STATVAR_DESCRIPTION"
          },
          "typeOf": [
            "TYPE_OF_DCID_3"
          ]
        },
      ]
    },
    ...
  ]
}

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`.

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.

Parameters:

nodes: "Q30"
property: "<-wikidataId->dcid"

GET Request:

curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Q30&property=%3C-wikidataId-%3Edcid'

POST Request:

curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
  https://api.datacommons.org/v2/resolve \
  -d '{"nodes": ["Q30"], "property": "<-wikidataId->dcid"}'

Response:

{
   "entities" : [
      {
         "node" : "Q30",
         "candidates" : [
            {
               "dcid" : "country/USA"
            }
         ],
      }
   ]
}

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 and longitude 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:

nodes: "37.42#-122.08"
property: "<-geoCoordinate->dcid"

GET Request:

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:

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"}'

Response:

{
   "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 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), the country Georgia (country/GEO) and the city Georgia in the US state of Vermont (geoId/5027700).

Note that the expression <-description->dcid is set implicitly.

Parameters:

nodes: "Georgia"

GET Request:

curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Georgia'

POST Request:

curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
  https://api.datacommons.org/v2/resolve \
  -d '{"nodes": ["Georgia"]}'

Response:

{ 
   "entities" : [
      {
        "node" : "Georgia",
        "candidates" : [
            {
               "dcid" : "geoId/13"
            },
            {
               "dcid" : "country/GEO"
            },
            {
               "dcid" : "geoId/5027700"
            }
         ],
      }
   ]
}

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:

nodes: "Georgia"
property: "<-description{typeOf:State}->dcid"

GET Request:

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:

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:

{
   "entities" : [
      {
         "node" : "Georgia",
         "candidates" : [
            {
               "dcid" : "geoId/13"
            }
         ],
      }
   ]
}

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:

nodes: "Mountain View, CA", "New York City"
property: "<-description{typeOf:City}->dcid"

GET Request:

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'

POST Request:

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"}'

Response:

{
   "entities" : [
      {
         "node" : "Mountain View, CA",
         "candidates" : [
            {
               "dcid" : "geoId/0649670"
            },
            {
               "dcid" : "geoId/0649651"
            }
         ],
      },
      {
         "node" : "New York City",
         "candidates" : [
            {
               "dcid" : "geoId/3651000"
            }
         ],
      }
   ]
}

Example 6: Find the DCID of a statistical variable

This queries datacommons.org for statistical variables containing the term “population”.

Parameters:

nodes: "population"
resolver: "indicator"

GET Request:

curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=population&resolver=indicator'

POST Request:

curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
  https://api.datacommons.org/v2/resolve \
  -d '{"nodes": ["population"], "resolver": "indicator"}'

Response:

(truncated)

{
  "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"
          ]
        },
        {
         // ...
         ]}]}

Page last updated: April 30, 2026 • Send feedback about this page