/v1/bulk/property/values/in/linked

Return property values for properties that can be chained for multiple degrees in the knowledge graph.

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

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 Knowledge Graph 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"
        }
      ]
    }
  ]
}