/v2/resolve

• Request
  • Query parameters
• Response
  • Response fields
• Examples
  • Example 1: Find the DCID of a place by another known ID
  • Example 2: Find the DCID of a place by coordinates
  • Example 3: Find the DCID of a place by name
  • Example 4: Find the DCID of a place by name, with a type filter
  • Example 5: Find the DCID of multiple places by name, with a type filter
  • Example 6: Find the DCID of a statistical variable
  • Example 7: Find the DCID of a non-place entity using its name
  • Example 8: Find the DCID of an entity using another field
• Supported place properties for Custom Data Commons

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

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:

{
  "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

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

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:

nodes: "Sustainable Development Goals"
property: "<-name"

GET Request:

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

POST Request:

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

Response:

{
  "entities": [
    {
      "node": "Sustainable Development Goals",
      "candidates": [
        {
          "dcid": "WHO/g/SustainableDevelopmentGoals"
        },
        {
          "dcid": "dc/g/SDG"
        },
        {
          "dcid": "dc/topic/sdg"
        }
      ]
    }
  ]
}

Example 8: Find the DCID of an entity using another field

This example looks up the DCID of a provenance by its URL.

Parameters:

nodes: "https://unstats.un.org/sdgs/dataportal"
property: "url"

GET Request:

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'

POST Request:

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

Response:

{
  "entities": [
    {
      "node": "https://unstats.un.org/sdgs/dataportal",
      "candidates": [
        {
          "dcid": "dc/base/UN_SDG"
        },
        {
          "dcid": "dc/d/UnitedNationsUn_SdgIndicatorsDatabase"
        }
      ]
    }
  ]
}

Supported place properties for Custom Data Commons

The following is a selection of properties that are supported as the property parameter for place resolutions:

Several region-specific codes are also supported:

• lgdCode (India)
• udiseCode (India)

Page last updated: August 11, 2026 • Send feedback about this page