info Note:
This API currently only supports the containedInPlace property to fetch Place nodes. Support for more properties and node types will be added in the future.

For example, in the following diagram:

Example of a chained property

The property containedInPlace is chained. Buenos Aires is contained in Argentina, which is itself contained in South America – implying Buenos Aires is also contained in South America. With this endpoint, you could query for countries in South America (returning Argentina) or for cities in South America (returning Buenos Aires).

info See Also:
For single requests with a simpler output, see the simple version of this endpoint.

Request

https://api.datacommons.org/v1/bulk/property/values/in/linked?property=containedInPlace&value_node_type={place_type}&nodes={parent_place_dcid_1}&nodes={parent_place_dcid_2}&key={your_api_key}

URL: https://api.datacommons.org/v1/bulk/property/values/in/linked Header: X-API-Key: {your_api_key} JSON Data: { "property": "containedInPlace", "value_place_type": "{place_type}", "nodes": [ "{parent_place_dcid_1}", "{parent_place_dcid_2}", ... ] }

Path Parameters

There are no path parameters for this endpoint.

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	DCIDs of the parent places to query.
value_node_type Required	string	Type of place to query for (e.g. city, county, state, etc.). For a list of available values, see the Graph Browser page on Place.
property Required	string	DCID of the property to query. Must be `containedInPlace`.

Response

The response looks like:

{
  "data":
  [
    {
      "node": "Parent Place 1 DCID",
      "values":
      [
        {
          "name": "Child Place Name",
          "dcid": "Child Place DCID"
        }, ...
      ]
    },
    {
      "node": "Parent Place 2 DCID",
      "values":
      [
        {
          "name": "Child Place Name",
          "dcid": "Child Place DCID"
        }, ...
      ]
    }, ...
  ]
}

Response fields

Name	Type	Description
node	string	DCID of the node queried.
values	list	list of nodes connected by the property queried.

Examples

Example 1: Get all states of multiple countries.

Get the states of the countries USA (DCID: ‘country/USA’) and India (DCID: ‘country/IND’). Note that this works because both countries have entries for the State class of places.

Request:

$ curl --request GET --url \
'https://api.datacommons.org/v1/bulk/property/values/in/linked?property=containedInPlace&value_node_type=State&nodes=country/USA&nodes=country/IND&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'

Request:

$ curl --request POST \
--url https://api.datacommons.org/v1/bulk/property/values/in/linked \
--header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \
--data '{"nodes":["country/USA", "country/IND"], "property":"containedInPlace", "value_node_type":"State"}'

Response:

{
  "data": [
    {
      "node": "country/USA",
      "values": [
        {
          "name": "Alabama",
          "dcid": "geoId/01"
        },
        {
          "name": "Alaska",
          "dcid": "geoId/02"
        },
        < ... output truncated for brevity ... >
        {
          "name": "Wyoming",
          "dcid": "geoId/56"
        },
        {
          "name": "Puerto Rico",
          "dcid": "geoId/72"
        }
      ]
    },
    {
      "node": "country/IND",
      "values": [
        {
          "name": "Gujarat",
          "dcid": "wikidataId/Q1061"
        },
        {
          "name": "Andhra Pradesh",
          "dcid": "wikidataId/Q1159"
        },
        < ... output truncated for brevity ... >
        {
          "name": "Daman and Diu",
          "dcid": "wikidataId/Q66710"
        },
        {
          "name": "Telangana",
          "dcid": "wikidataId/Q677037"
        }
      ]
    }
  ]
}