/v2/resolve

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 and returns the DCIDs of matches. You can use common properties or even descriptive words to find entities.

For example, you could query for “San Francisco, CA” or “San Francisco” to find that its DCID is geoId/0667000. You can also provide the type of entity (country, city, state, etc.) to disambiguate (Georgia the country vs. Georgia the US state).

Request

https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=DCID_LIST&property=RELATION_EXPRESSION
URL: https://api.datacommons.org/v2/resolve Header: X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI JSON data: { "nodes": [ "NODE_DCID_1", "NODE_DCID_2", ... ], "property": "RELATION_EXPRESSION" }

Query parameters

Name Type Description
key
Required
string Your API key. See the page on authentication for a demo key, as well as instructions on how to get your own key.
nodes
Required
list of strings Comma-separated list of property values (e.g. entity name or DCID), or description of the node. This currently only supports the name of a place.
property
Required
string Relation expression that represents the relation of the given nodes to the queried entities. Note that this should always end with ->dcid

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.

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"

Request:

curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&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.

Note: If using a GET request, use the percent code %23 for #.

Parameters:

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

Request:

curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=37.42%23-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"

Request:

curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&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.

Note: When sending a GET request, you need to use the following percent codes for reserved characters:

  • %7B for {
  • %7D for }

Parameters:

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

Request:

curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Georgia&property=<-description%7BtypeOf:State%7D->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”.

Note: When sending a GET request, you need to use the following percent codes for reserved characters:

  • %20 for space
  • %7B for {
  • %7D for }

Parameters:

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

Request (GET):

curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Mountain%20View,%20CA&nodes=New%20York%20City&property=<-description%7BtypeOf:City%7D->dcid'

Request (POST):

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