/v1/bulk/observations/point/linked

Retrieve a single observation of multiple variables at a set date 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 an observation for all places within an ancestor place. For example, this could be getting the population of women in 2018 for all states in the United States.

info Note:
Currently, this endpoint only supports the containedInPlace property and Place entities. Support for other properties and entity types will be added in the future.

info See Also:
To get a single observation for a single place, see /v1/observations/point.
To get a series of observations for all places within an ancestor place, see /v1/bulk/observations/series/linked.

Request

https://api.datacommons.org/v1/bulk/observations/point/linked?linked_property=containedInPlace&linked_entity={ancestor_place_dcid}&entity_type={place_type}&variables={variable_dcid_1}&variables={variable_dcid_2}&date={date}&key={your_api_key}

URL: https://api.datacommons.org/v1/bulk/observations/point/linked Header: X-API-Key: {your_api_key} JSON Data: { "linked_property": "containedInPlace", "linked_entity": "{ancestor_place_dcid}" "entity_type": "{place_type}", "date": "{date}", "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	DCIDs 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 Graph Browser 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`.
date Optional	string	Datetime of measurement of the value requested in ISO 8601 format. To see the dates available, look up the variable in the Statistical Variable Explorer. If date is not provided, the latest available datapoint is returned.
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",
      "observationsByEntity":
      [
        {
          "entity": "entity_dcid",
          "pointsByFacet":
          [
            {
              "date": "YYYY-MM-DD",
              "value": 1234,
              "facet": 0123456789
            }
          ]
        }, ...
      ]
    }, ...
  ],
  "facets":
  {
    "0123456789":
    {
      "importName": "ImoprtName",
      "provenanceUrl": "https://provenance.url/here",
      "measurementMethod": "MeasurementMethod",
      "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.
facets	object	Metadata on the facet(s) the data came from. Can include things like provenance, measurement method, and units.

Examples

Example 1: Get a single observation from multiple variables at a set date for all places within a ancestor place.

Get the population (DCID: Count_Person) and median income (DCID: Median_Income_Person) for all states in the US (DCID: country/USA) in the year 2020.

Request:

$ curl --request GET --url \
'https://api.datacommons.org/v1/bulk/observations/point/linked?linked_entity=country/USA&linked_property=containedInPlace&variables=Count_Person&variables=Median_Income_Person&entity_type=State&date=2020&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'

Request:

$ curl --request POST \
--url https://api.datacommons.org/v1/bulk/observations/point/linked \
--header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \
--data '{"linked_property":"containedInPlace", "linked_entity":"country/USA", "entity_type":"State", "date":"2020", "variables":["Count_Person", "Median_Income_Person"]}'

Response:

{
  "observationsByVariable":
  [
    {
      "variable": "Count_Person",
      "observationsByEntity":
      [
        {
          "entity": "geoId/01",
          "pointsByFacet":
          [
            {
              "date": "2020",
              "value": 4921532,
              "facet": 2176550201
            }
          ]
        },
        {
          "entity": "geoId/02",
          "pointsByFacet":
          [
            {
              "date": "2020",
              "value": 731158,
              "facet": 2176550201
            }
          ]
        },
        < ... output truncated for brevity ... >
        {
          "entity": "geoId/56",
          "pointsByFacet":
          [
            {
              "date": "2020",
              "value": 582328,
              "facet": 2176550201
            }
          ]
        },
        {
          "entity": "geoId/72",
          "pointsByFacet":
          [
            {
              "date": "2020",
              "value": 3255642,
              "facet": 1145703171
            }
          ]
        }
      ]
    },
    {
      "variable": "Median_Income_Person",
      "observationsByEntity":
      [
        {
          "entity": "geoId/01",
          "pointsByFacet":
          [
            {
              "date": "2020",
              "value": 27030,
              "facet": 1305418269
            }
          ]
        },
        {
          "entity": "geoId/02",
          "pointsByFacet":
          [
            {
              "date": "2020",
              "value": 34881,
              "facet": 1305418269
            }
          ]
        },
        < ... output truncated for brevity ... >
        {
          "entity": "geoId/56",
          "pointsByFacet":
          [
            {
              "date": "2020",
              "value": 33031,
              "facet": 1305418269
            }
          ]
        },
        {
          "entity": "geoId/72",
          "pointsByFacet":
          [
            {
              "date": "2020",
              "value": 13814,
              "facet": 1305418269
            }
          ]
        }
      ]
    }
  ],
  "facets":
  {
    "2176550201":
    {
      "importName": "USCensusPEP_Annual_Population",
      "provenanceUrl": "https://www2.census.gov/programs-surveys/popest/tables",
      "measurementMethod": "CensusPEPSurvey",
      "observationPeriod": "P1Y"
    },
    < ... output truncated for brevity ... >
    "1305418269":
    {
      "importName": "CensusACS5YearSurvey",
      "provenanceUrl": "https://www.census.gov/",
      "measurementMethod": "CensusACS5yrSurvey",
      "unit": "USDollar"
    }
  }
}