/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).

info Note:
Currently, this endpoint only supports place entities. Support for other entity types will be added as the knowledge graph grows.

priority_highIMPORTANT:
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.

info See Also:
For querying multiple entities, see the bulk version of this endpoint.

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: December 17, 2024 • Send feedback about this page