/v1/bulk/observations/point

Retrieve a specific observation at a set date from multiple variables for multiple entities.

Request

https://api.datacommons.org/v1/bulk/observations/point?entities={entity_dcid_1}&entities={entity_dcid_2}&variables={variable_dcid_1}&variables={variable_dcid_2}&key={your_api_key}
URL: https://api.datacommons.org/v1/bulk/observations/point Header: X-API-Key: {your_api_key} JSON Data: { "entities": [ "{entity_dcid_1}", "{entity_dcid_2}", ... ], "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.
entities
Required		 Repeated string DCIDs of the entities the variables describe.
variables
Required		 Repeated string DCIDs of the variables to query observations for.
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": "variable1_DCID",
      "observationsByEntity": [
        {
          "entity": "entity1_DCID",
          "pointsByFacet": [
            {
              "date": "YYYY",
              "value": 1234,
              "facet": 1234567890
            }, ...
          ]
        },
      ]
    }
  ],
  "facets": {
    "1234567890": {
      "importName": "Import_name_string",
      "provenanceUrl": "https://provenance.url",
      "measurementMethod": "MeasurementMethod"
    } ...     
  }
}

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 values for multiple variables and entities from the preferred facet at a set date

Get latest count of men (DCID: Count_Person_Male ) and count of women (DCID: Count_Person_Female ) for both California (DCID: geoId/06 ) and Texas (DCID: geoId/48 ) in 2019.

  • Request:

    $ curl --request GET --url \
'https://api.datacommons.org/v1/bulk/observations/point?entities=geoId/06&entities=geoId/48&variables=Count_Person_Male&variables=Count_Person_Female&date=2019&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'

  • Request:

    $ curl --request POST \
--url https://api.datacommons.org/v1/bulk/observations/point \
--header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \
--data '{"entities":["geoId/06", "geoId/48"], "variables":["Count_Person_Male", "Count_Person_Female"], "date":"2019"}'

Response:

{
  "observationsByVariable": [
    {
      "variable": "Count_Person_Male",
      "observationsByEntity": [
        {
          "entity": "geoId/06",
          "pointsByFacet": [
            {
              "date": "2019",
              "value": 19526298,
              "facet": 1145703171
            }
          ]
        },
        {
          "entity": "geoId/48",
          "pointsByFacet": [
            {
              "date": "2019",
              "value": 14034009,
              "facet": 1145703171
            }
          ]
        }
      ]
    },
    {
      "variable": "Count_Person_Female",
      "observationsByEntity": [
        {
          "entity": "geoId/06",
          "pointsByFacet": [
            {
              "date": "2019",
              "value": 19757199,
              "facet": 1145703171
            }
          ]
        },
        {
          "entity": "geoId/48",
          "pointsByFacet": [
            {
              "date": "2019",
              "value": 14226847,
              "facet": 1145703171
            }
          ]
        }
      ]
    }
  ],
  "facets": {
    "1145703171": {
      "importName": "CensusACS5YearSurvey",
      "provenanceUrl": "https://www.census.gov/",
      "measurementMethod": "CensusACS5yrSurvey"
    }
  }
}

Example 2: Get values for multiple variables and entities from all facets

Get latest count of men (DCID: Count_Person_Male ) and count of women (DCID: Count_Person_Female ) for both California (DCID: geoId/06 ) and Texas (DCID: geoId/48 ) for all facets.

Request:

$ curl --request GET --url \
'https://api.datacommons.org/v1/bulk/observations/point?entities=geoId/06&entities=geoId/48&variables=Count_Person_Male&variables=Count_Person_Female&all_facets=true&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'

Response:

{
  "observationsByVariable": [
    {
      "variable": "Count_Person_Male",
      "observationsByEntity": [
        {
          "entity": "geoId/06",
          "pointsByFacet": [
            {
              "date": "2019",
              "value": 19526298,
              "facet": 1145703171
            },
            {
              "date": "2019",
              "value": 19640794,
              "facet": 1226172227
            },
            {
              "date": "2019",
              "value": 19523898.009,
              "facet": 10983471
            },
            {
              "date": "2019",
              "value": 19523898.009,
              "facet": 196790193
            },
            {
              "date": "2018",
              "value": 19663600,
              "facet": 1151455814
            }
          ]
        },
        {
          "entity": "geoId/48",
          "pointsByFacet": [
            {
              "date": "2019",
              "value": 14034009,
              "facet": 1145703171
            },
            {
              "date": "2019",
              "value": 14385762,
              "facet": 1226172227
            },
            {
              "date": "2019",
              "value": 14045645.432,
              "facet": 10983471
            },
            {
              "date": "2019",
              "value": 14045645.432,
              "facet": 196790193
            },
            {
              "date": "2018",
              "value": 14260100,
              "facet": 1151455814
            }
          ]
        }
      ]
    },
    {
      "variable": "Count_Person_Female",
      "observationsByEntity": [
        {
          "entity": "geoId/06",
          "pointsByFacet": [
            {
              "date": "2019",
              "value": 19757199,
              "facet": 1145703171
            },
            {
              "date": "2019",
              "value": 19871429,
              "facet": 1226172227
            },
            {
              "date": "2019",
              "value": 19759598.991,
              "facet": 10983471
            },
            {
              "date": "2019",
              "value": 19759598.991,
              "facet": 196790193
            },
            {
              "date": "2018",
              "value": 19817700,
              "facet": 1151455814
            }
          ]
        },
        {
          "entity": "geoId/48",
          "pointsByFacet": [
            {
              "date": "2019",
              "value": 14226847,
              "facet": 1145703171
            },
            {
              "date": "2019",
              "value": 14610119,
              "facet": 1226172227
            },
            {
              "date": "2019",
              "value": 14215210.568,
              "facet": 10983471
            },
            {
              "date": "2019",
              "value": 14215210.568,
              "facet": 196790193
            },
            {
              "date": "2018",
              "value": 14250900,
              "facet": 1151455814
            }
          ]
        }
      ]
    }
  ],
  "facets": {
    "10983471": {
      "importName": "CensusACS5YearSurvey_SubjectTables_S2601A",
      "provenanceUrl": "https://data.census.gov/cedsci/table?q=S2601A&tid=ACSST5Y2019.S2601A",
      "measurementMethod": "CensusACS5yrSurveySubjectTable"
    },
    "196790193": {
      "importName": "CensusACS5YearSurvey_SubjectTables_S2602",
      "provenanceUrl": "https://data.census.gov/cedsci/table?q=S2602&tid=ACSST5Y2019.S2602",
      "measurementMethod": "CensusACS5yrSurveySubjectTable"
    },
    "1145703171": {
      "importName": "CensusACS5YearSurvey",
      "provenanceUrl": "https://www.census.gov/",
      "measurementMethod": "CensusACS5yrSurvey"
    },
    "1151455814": {
      "importName": "OECDRegionalDemography",
      "provenanceUrl": "https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR#",
      "measurementMethod": "OECDRegionalStatistics",
      "observationPeriod": "P1Y"
    },
    "1226172227": {
      "importName": "CensusACS1YearSurvey",
      "provenanceUrl": "https://www.census.gov/",
      "measurementMethod": "CensusACS1yrSurvey"
    }
  }
}

Page last updated: December 17, 2024 • Send feedback about this page