/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.
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.
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
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 |
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 |
string | Description of the entity. Typically the name of the place. |
| type |
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"]}