Introduction

The Data USA API allows users to explore the entire database using carefully constructed query strings, returning data as JSON results. All of the visualizations on the page have a "show data" button on their top-right that displays the API call(s) used to generate that visualization. Additionally, the new Viz Builder is a great way to explore what's possible. This page illustrates an example usage of exploring geographic data.

Example: Population Data

To get population data at the national level we can use the following API call:

https://datausa.io/api/data?drilldowns=Nation&measures=Population

Now let’s take a look at the output and break it down

{
  "data":[
    {
      "ID Nation": "01000US",
      "Nation": "United States",
      "ID Year": 2016,
      "Year": "2016",
      "Population": 323127515,
      "Slug Nation": "united-states"
    },
    {
      "ID Nation": "01000US",
      "Nation": "United States",
      "ID Year": 2015,
      "Year": "2015",
      "Population": 321418821,
      "Slug Nation": "united-states"
    },
    {
      "ID Nation": "01000US",
      "Nation": "United States",
      "ID Year": 2014,
      "Year": "2014",
      "Population": 318857056,
      "Slug Nation": "united-states"
    },
    {
      "ID Nation": "01000US",
      "Nation": "United States",
      "ID Year": 2013,
      "Year": "2013",
      "Population": 316128839,
      "Slug Nation": "united-states"
    }
  ],
  "source": [
    {
      "measures": ["Population"],
      "annotations": {
        "source_name": "Census Bureau",
        "source_description": "Census Bureau conducts surveys of the United States Population, including the American Community Survey",
        "dataset_name": "ACS 1-year Estimate",
        "dataset_link": "http: //www.census.gov/programs-surveys/acs/",
        "table_id": "B01003",
        "topic": "Diversity"
      },
      "name": "acs_yg_total_population_1",
      "substitutions": [ ]
    }
  ]
}

Data

The data section of the JSON result contains an object for each row of data. By default, the API returns as many years possible from the data. To only retrieve the latest year’s data, use:

https://datausa.io/api/data?drilldowns=Nation&measures=Population&year=latest

This call gives us the population of the US based on the latest available year of data. Using the string "latest" instead of a hard-coded year ensures that if the underlying data is updated with a new year's worth of data, the API calls will all reflect this new data automatically. Additionally, to get data at the state level we can use:

https://datausa.io/api/data?drilldowns=State&measures=Population&year=latest

Source

You may have noticed some additional information returned with each API call. The source section identifies the underlying data table where the rows have been retrieved from for the given request. The substitutions section will indicate whether any input variables have been substituted for the purposes of providing data (instead of providing no data). If the subs dictionary is empty, then no subsitutions have been made.