/v2/resolve

Request
- Query parameters
Response
- Response fields
Examples

The Resolve API returns a Data Commons ID (DCID) for entities in the graph. 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.

Note that you can only resolve entities by some terminal properties. You cannot resolve properties that represent linked entities with incoming or outgoing arc relationships. For that, you need to use the Node API. For example, if you wanted to get all the DCIDs of entities that are related to a given entity by the containedInPlace property (say, all states in the United States), use the Node API.

Note: Currently, this endpoint only supports place entities.

IMPORTANT: This endpoint relies on name-based geocoding and is prone to inaccuracies. One common pattern is ambiguous place names that exist 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, please provide as much context in the description as possible. For example, to resolve Cambridge in USA, pass “Cambridge, MA, USA” if you can.

Request

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

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

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.
property Required	string	An expression that describes the identifier used in the `nodes` parameter. Only three are currently supported: `<-description`: Search for nodes based on name-related properties (such as `name`, `alternateName`, etc.). `<-wikidataId`: Search for nodes based on their Wikidata ID(s). `<-geoCoordinates`: Search for nodes based on latitude and/or longitude. Note that these are not necessarily “properties” that appear in the knowledge graph; instead, they are “synthetic” attributes that cover searches over multiple properties. Each expression must end with `->dcid` and may optionally include a `typeOf` filter.

Response

The response looks like:

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

Response fields

Name	Type	Description
node	string	The property value or description provided.
candidates	list	DCIDs matching the description you provided.
dominantType	string	Optional field which, where present, disambiguates between multiple results.

Note: There is a deprecated field resolvedIds that is currently returned by the API. It will be removed soon. Examples below omit this redundant field.

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 the description property in the request. This currently only supports resolving place entities by name.

Parameters:

nodes: "Georgia"
property: "<-description->dcid"

GET Request:

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

POST Request:

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

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

Page last updated: March 27, 2025 • Send feedback about this page