/v1/bulk/observations/series/linked

Returns observations of multiple variables for entities linked to an ancestor entity by the same property.

More specifically, in the following diagram:

Example of a linked property

The property containedInPlace is linked. 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 observations for Argentina) or for cities in South America (returning observations for Buenos Aires).

This is useful for retrieving observations for all places within an ancestor place. For example, this could be getting the population of women for all states in the United States.

Request

https://api.datacommons.org/v1/bulk/observations/series/linked?linked_property=containedInPlace&linked_entity={ancestor_place_dcid}&entity_type={place_type}&variables={variable_dcid_1}&variables={variable_dcid_2}&key={your_api_key}
URL: https://api.datacommons.org/v1/bulk/observations/series/linked Header: X-API-Key: {your_api_key} JSON Data: { "linked_property": "containedInPlace", "linked_entity": "{ancestor_place_dcid}" "entity_type": "{place_type}", "variables": [ "{variable_dcid_1}", "{variable_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.
linked_entity
Required		 list DCID of the ancestor place to query.
entity_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.
variables
Required		 list DCIDs of the variables to query.
linked_property
Required		 string DCID of the property to query. Must be containedInPlace.
all_facets
Optional		 boolean Whether to return data from all facets available. If true, data from all facets available will be returned. If false, only data from the preferred facet will be returned. Defaults to false.

Response

The response looks like:

{
  "observationsByVariable":
  [
    {
      "variable": "variable_dcid_1",
      "observationsByEntity":
      [
        {
          "entity": "entity_dcid_1",
          "seriesByFacet":
          [
            {
              "series":
              [
                {
                  "date": "YYYY-MM-DD",
                  "value": 1234
                }, ...
              ],
              "facet": 0123456789
            }
          ]
        }, ...
      ]
    }, ...
  ],
  "facets":
  {
    "0123456789":
    {
      "importName": "import_name_here",
      "provenanceUrl": "https://provenance.url/here",
      "measurementMethod": "measurement_method_here",
      "observationPeriod": "P<N>Y"
    }
  }
}

Response fields

Name Type Description
observationsByVariable list List of observations organized by variable. These are further organized by entity, and then by facet. Observations are returned in chronological order.
facets object Metadata on the facet(s) the data came from. Can include things like provenance, measurement method, and units.

Examples

Example 1: Get observations for all places within an ancestor place.

Get the population (DCID: Count_Person) for all counties in the US state of Delaware (DCID: geoId/10).

  • Request:

    $ curl --request GET --url \
'https://api.datacommons.org/v1/bulk/observations/series/linked?linked_entity=geoId/10&linked_property=containedInPlace&variables=Count_Person&entity_type=County&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'

  • Request:

    $ curl --request POST \
--url https://api.datacommons.org/v1/bulk/observations/series/linked \
--header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \
--data '{"linked_entity":"geoId/10", "linked_property":"containedInPlace", "entity_type":"County", variables:"Count_Person"}'

Response:

{
  "observationsByVariable":
  [
    {
      "variable": "Count_Person",
      "observationsByEntity":
      [
        {
          "entity": "geoId/10001",
          "seriesByFacet":
          [
            {
              "series":
              [
                {
                  "date": "1970",
                  "value": 81892
                },
                < ... output truncated for brevity ... >
                {
                  "date": "2021",
                  "value": 184149
                }
              ],
              "facet": 2176550201
            }
          ]
        },
        {
          "entity": "geoId/10003",
          "seriesByFacet":
          [
            {
              "series":
              [
                {
                  "date": "1970",
                  "value": 385856
                },
                < ... output truncated for brevity ... >
                {
                  "date": "2021",
                  "value": 571708
                }
              ],
              "facet": 2176550201
            }
          ]
        },
        {
          "entity": "geoId/10005",
          "seriesByFacet":
          [
            {
              "series":
              [
                {
                  "date": "1970",
                  "value": 80356
                },
                < ... output truncated for brevity ... >
                {
                  "date": "2021",
                  "value": 247527
                }
              ],
              "facet": 2176550201
            }
          ]
        }
      ]
    }
  ],
  "facets":
  {
    "2176550201":
    {
      "importName": "USCensusPEP_Annual_Population",
      "provenanceUrl": "https://www2.census.gov/programs-surveys/popest/tables",
      "measurementMethod": "CensusPEPSurvey",
      "observationPeriod": "P1Y"
    }
  }
}