/v1/info/variable

Get basic information about a variable.

This API returns basic information on a variable, given the variable’s DCID. The information provided includes the number of entities that have data for the variable, the minimum and maximum value observed, and the name and DCID of the top 3 entities with highest observed values for that variable. The information is grouped by place type (country, state, county, etc.).

Request

GET Request

https://api.datacommons.org/v1/info/variable/{VARIABLE_DCID}?key={your_api_key}

Path Parameters

Name Description
VARIABLE_DCID
Required
DCID of the variable to query information for.

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.

Response

The response looks like:

{
  "node": "dcid",
  "info": {
    "placeTypeSummary": {
      "Country/State/City/Etc": {
        "topPlaces": [{ "dcid": "dcid", "name": "Place Name" }],
        "placeCount": 123,
        "minValue": 123456,
        "maxValue": 123456
      }, ...
    },
    "provenanceSummary": {
      "provenance_dcid": {
        "importName": "Import_Name",
        "releaseFrequency": "P<N>Y",
        "seriesSummary": [
          {
            "seriesKey": { "observationPeriod": "P<N>Y" },
            "earliestDate": "YYYY-MM-DD",
            "latestDate": "YYYY-MM-DD",
            "placeTypeSummary": {
              "County/Country/State/Etc": {
                "topPlaces": [
                  { "dcid": "dcid", "name": "Place Name" },
                  { "dcid": "dcid", "name": "Place Name" },
                  { "dcid": "dcid", "name": "Plance Name" }
                ],
                "placeCount": 123,
                "minValue": 12,
                "maxValue": 123456
              }, ...
            },
            "minValue": 12,
            "maxValue": 123456,
            "observationCount": 123,
            "timeSeriesCount": 123
          }
        ],
        "observationCount": 1234,
        "timeSeriesCount": 1234
      }
    }
  }
}

Response fields

Name Type Description
node string DCID of the variable queried.
info object Information about the variable queried. Includes maximum and minimum values, and number of places with data on the variable queried, grouped by place type (country-level, state-level, city-level, etc. statistics are grouped together). Also includes information about the provenance of data for the variable queried.

Examples

Example 1: Get information on a single variable

Get basic information about the variable for number of farms (DCID: Count_Farm).

Request:

$ curl --request GET --url \
'https://api.datacommons.org/v1/info/variable/Count_Farm?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'

Response:

{
  "node": "Count_Farm",
  "info": {
    "placeTypeSummary": {
      "Country": {
        "topPlaces": [{ "dcid": "country/USA", "name": "United States" }],
        "placeCount": 1,
        "minValue": 123456,
        "maxValue": 2042220
      },
      "State": {
        "topPlaces": [
          { "dcid": "geoId/06", "name": "California" },
          { "dcid": "geoId/48", "name": "Texas" },
          { "dcid": "geoId/12", "name": "Florida" }
        ],
        "placeCount": 50,
        "minValue": 990,
        "maxValue": 248416
      },
      "County": {
        "topPlaces": [
          { "dcid": "geoId/06037", "name": "Los Angeles County" },
          { "dcid": "geoId/17031", "name": "Cook County" },
          { "dcid": "geoId/48201", "name": "Harris County" }
        ],
        "placeCount": 3076,
        "minValue": 2,
        "maxValue": 5551
      }
    },
    "provenanceSummary": {
      "dc/m02b5p": {
        "importName": "USDA_AgricultureCensus",
        "releaseFrequency": "P5Y",
        "seriesSummary": [
          {
            "seriesKey": { "observationPeriod": "P5Y" },
            "earliestDate": "2017",
            "latestDate": "2017",
            "placeTypeSummary": {
              "County": {
                "topPlaces": [
                  { "dcid": "geoId/06037", "name": "Los Angeles County" },
                  { "dcid": "geoId/17031", "name": "Cook County" },
                  { "dcid": "geoId/48201", "name": "Harris County" }
                ],
                "placeCount": 3076,
                "minValue": 2,
                "maxValue": 5551
              },
              "Country": {
                "topPlaces": [
                  { "dcid": "country/USA", "name": "United States" }
                ],
                "placeCount": 1,
                "minValue": 2042220,
                "maxValue": 2042220
              },
              "State": {
                "topPlaces": [
                  { "dcid": "geoId/06", "name": "California" },
                  { "dcid": "geoId/48", "name": "Texas" },
                  { "dcid": "geoId/12", "name": "Florida" }
                ],
                "placeCount": 50,
                "minValue": 990,
                "maxValue": 248416
              }
            },
            "minValue": 2,
            "maxValue": 2042220,
            "observationCount": 3127,
            "timeSeriesCount": 3127
          }
        ],
        "observationCount": 3127,
        "timeSeriesCount": 3127
      }
    }
  }
}