U.S. flag

An official website of the United States government

Skip Header
About
Guidance
Latest Releases
Search data, events, resources, and more

Census Microdata API User Guide

The purpose of this guide is to provide an overview of the U.S. Census Bureau’s microdata application programming interface (API) and walk through how to make queries. Through this guide, you will learn what the microdata API is, when to use it, and how to use it to get raw data and custom statistics.

Types of Microdata API Queries
  • What is Public Use Microdata
  • What is the Microdata API
  • Dataset Types
  • Types of Microdata API Queries
  • Terms
  • Additional Concepts
  • How To Create API Queries
  • Limitations, Contact Us & Appendix
Types of Microdata API Queries

Types of Microdata API Queries: Raw Data or Custom Statistics

Depending on the type of API request you use, the microdata API provides results for untabulated records or custom statistics:

Raw, Untabulated Records: Use the get parameter ?get= in your API queries

For example, this API query provides the raw data for sex, disability status, and person statistical weight for people without health insurance in Maryland, Virginia, and the District of Columbia: api.census.gov/data/2019/acs/acs1/pums?get=SEX,DIS,PWGTP&HICOV=2&for=state:11,24,51. Step-by-step instructions on how to create this API query are covered later in this guide, but for now, let’s focus on the results of the data request.

Figure 2: API "Get" Query Results Provide Data for Individual Records api.census.gov/data/2019/acs/acs1/pums?get=SEX,DIS,PWGTP&HICOV=2&for=state:11,24,51

The results show 8,589 records. Each record represents a single person and shows their sex, disability status, statistical weight, health insurance status, and state of residence. For example, you can see the first record of the API query in Figure 2 represents a single person whose characteristics include:

  • Male (SEX=1)
  • No disabilities (DIS=2)
  • Statistical weight of 88 (PWGTP=88)
  • No health insurance (HICOV=2)
  • Lives in Virginia (state=51)

Custom Statistics in a Table Format: Use the tabulate parameter ?tabulate= in your API queries

In your tabulate API queries, you will need to specify whether you want variables to appear in rows &row+ or columns &col+, and you will often want to include a statistical weight in your query.

For example, this API query provides results for sex by disability status for the population without health insurance in DC, MD, and VA: api.census.gov/data/2019/acs/acs1/pums?tabulate=weight(PWGTP)&col+for&row+SEX&row+DIS&HICOV=2&for=state:11,24,51. Step-by-step instructions on how to create this API query are covered later in this guide, but for now, let’s focus on the results of the data request.

Figure 3: API "Tabulate" Query Results Provide Data for Custom Statistics api.census.gov/data/2019/acs/acs1/pums?tabulate=weight(PWGTP)&col+for&row+SEX&row+DIS&HICOV=2&for=state:11,24,51

The results provide a custom table. Each estimate from this table is a weighted tabulation that has been aggregated to represent the population without health insurance (HICOV=2) in each of the three states. From the first row of data in Figure 3, you can see in 2019 there were an estimated:

  • 1,591 men (SEX=1) with a disability (DIS=1) without health insurance in DC (state=11)
  • 13,598 men with a disability without health insurance in MD (state=24)
  • 39,616 men with a disability without health insurance in VA (state=51)

The next row of data in Figure 3 shows these same statistics for women (SEX=2). The third and fourth rows of data show the same information that the first two rows do, except that they represent people without a disability (DIS=2).

You can obtain these same results through Microdata Access on data.census.gov/mdat. The data from the API query are shown below, and the tool also calculates totals.

Figure 4: Microdata Access Results https://data.census.gov/mdat/#/search?ds=ACSPUMS1Y2019&cv=ucgid&rv=DIS,SEX&nv=HICOV(2)&wt=PWGTP&g=0400000US11,24,51

Page Last Revised - December 21, 2023
Is this page helpful?
Thumbs Up Image Yes Thumbs Down Image No
NO THANKS
255 characters maximum 255 characters maximum reached
Thank you for your feedback.
Comments or suggestions?

Top

Back to Header