No results found
Show all results

Introduction

At its core, the Data USA API allows users to show data across various levels of detail, called sumlevels. There are four core categories of data: geographies, occupations, industries and educational studies. This page illustrates an example usage of exploring geographic data. Full documentation for the Data USA API is available on the Github repository wiki.

Exploring Population Data

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

https://api.datausa.io/api?show=geo&sumlevel=nation&required=pop

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

          {
            "data":
              [
               [2013, "01000US", 311536594],
               [2014, "01000US", 314107084]
              ],
            "headers": ["year", "geo", "pop"],
            ...
          }
      

The data section of the JSON result contains a list of rows of data. Each header represents the respective data element in each row. For example, 2013 the first item in the first row, represents a "year" since year is the first item in the header array.

The previous API call will return data for all available years in the database. To only retrieve the latest year’s data, use:

https://api.datausa.io/api?show=geo&sumlevel=nation&year=latest&required=pop

This call gives us the popoulation of the US based on the latest available year of data. To get data at the state level we can use:

https://api.datausa.io/api?show=geo&sumlevel=state&year=latest&required=pop

Additional information

You may have noticed some additional pieces of information returned with each API call. The logic section represents the list of possible data sources the API could use to fulfill a given request. The logic section is a list of dictionaries with information on each possible data table.

        "logic": [
          {"dataset": "ACS 5-year Estimate",
          "link": "http://www.census.gov/programs-surveys/acs/",
          "org": "Census Bureau",
          "supported_levels": {"geo": ["nation", "state", "county", "msa", "puma", "place", "tract", "all"]}, "table": "yg"},
          {"dataset": "ACS 1-year Estimate",
          "link": "http://www.census.gov/programs-surveys/acs/",
          "org": "Census Bureau",
          "supported_levels": {"geo": ["nation", "state", "county", "msa", "place", "all"]}, "table": "yg"}
        ],
        ...
      

The source section represents the actual table used for processing the API call.

        "source": {"dataset": "ACS 5-year Estimate", "link": "http://www.census.gov/programs-surveys/acs/", "org": "Census Bureau", "supported_levels": {"geo": ["nation", "state", "county", "msa", "puma", "place", "tract", "all"]}, "table": "yg"},
      

The subs section will indicate whether any input variables have been substituted for purposes of providing data (instead of providing no data). If the subs dictionary is empty, then no subsitutions have been made.

          "subs": {}