/v1/find/entities

Find the DCID of a given entity.

Given the description of an entity, this endpoint searches for an entry in the Data Commons knowledge graph and returns the DCIDs of matches. 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

GET Request

URL: https://api.datacommons.org/v1/find/entities?key={your_api_key}&description={entity_description}

Path Parameters

There are no path parameters for this end point.

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.
description
Required
string Description of the entity. Typically the name of the place.
type
Optional
string The type of entity, specified as a DCID. Common values are “Country”, “State”, “County”, “City”.

Response

The response looks like:

{
  "dcids": ["dcid"]
}

Response fields

Name Type Description
dcids list DCIDs matching the description you provided. If no matches are found, this field will not be returned.

Examples

Example 1: Find the DCID of a place

This queries for the DCID of “Georgia”. Notice that specifying “Georgia” without specifying type returned the DCID of the US state.

Request:

$ curl --request GET --url \
'https://api.datacommons.org/v1/find/entities?description=Georgia&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'

Response:

{"dcids":["geoId/13"]}

Example 2: Find the DCID of a place, including a type

This queries for the DCIDs of “Georgia” while specifying we want the country.

Request:

$ curl --request GET --url \
'https://api.datacommons.org/v1/find/entities?description=Georgia&type=Country&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'

Response:

{"dcids":["country/GEO"]}

Page last updated: November 27, 2024 • Send feedback about this page