Use these steps to create API calls that provide the raw microdata records for your requested variables. For this example, we will request data for the untabulated records on sex, disability status, and person statistical weight for the population without health insurance in DC, MD, and VA based on the 2019 ACS 1-Year PUMS.

https://api.census.gov/data/2019/acs/acs1/pums?get=SEX,DIS,PWGTP&HICOV=2&for=state:11,24,51

1.      Base API URL

Begin your API queries with the base URL. You can find it in the API Discovery Tool for your dataset. The example below shows the base URL for the 2019 American Community Survey (ACS) 1-Year PUMS.

https://api.census.gov/data/2019/acs/acs1/pums

2.     Add Get Statement

Add the get function ?get= to the API query. This specifies that you want raw data for untabulated records.

https://api.census.gov/data/2019/acs/acs1/pums?get=

3.     Add Your Variables and Statistical Weights

Add your desired variables and weights, separated by a comma. In this dataset, SEX and DIS provide data for sex and disability status. PWGTP is the person-level statistical weight for each record. See the “variables” section of the API Discovery Tool for this dataset to explore a list of available variables.

https://api.census.gov/data/2019/acs/acs1/pums?get=SEX,DIS,PWGTP

4.     Restrict Your Universe

If you would like to limit your universe, add predicates to restrict your results by variable value. For example, the predicate &HICOV=2 limits results to only include data for the population without health insurance.

https://api.census.gov/data/2019/acs/acs1/pums?get=SEX,DIS,PWGTP&HICOV=2

5.     Add Your Geography

Add your geography. For example, the predicate &for=state:11,24,51 limits results to only include data for the District of Columbia, Maryland, and Virginia. See the “examples” section of the API Discovery Tool for this dataset to explore the available geographic levels.

https://api.census.gov/data/2019/acs/acs1/pums?get=SEX,DIS,PWGTP&HICOV=2&for=state:11,24,51

6.     View Results

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. The first few rows of the output are displayed as follows. You can save these results as a .csv file or consume the data in its original JavaScript Object Notation (JSON) file format.

[["SEX","DIS","PWGTP","HICOV","state"],

["1","1","57","2","51"],

["1","2","118","2","24"],

["1","2","114","2","11"],

["1","1","76","2","51"],

["1","1","73","2","51"],

["1","2","46","2","51"],

["1","2","51","2","51"],

["1","2","78","2","51"],

….

Use these steps to create API calls that provide custom statistics in a table format. Many of the steps in tabulate queries are similar to the steps used in get queries, but there are key differences. In this example, we will find data on the total number of males and females by disability status who do not have health insurance in DC, MD, and VA based on the 2019 ACS 1-Year PUMS.

https://api.census.gov/data/2019/acs/acs1/pums?tabulate=weight(PWGTP)&col+for&row+SEX&row+DIS&HICOV=2&for=state:11,24,51

1.      Base API URL

Begin your API queries with the base URL. You can find it in the API Discovery Tool for your dataset. The example below shows the base URL for the 2019 American Community Survey (ACS) 1-Year PUMS.

https://api.census.gov/data/2019/acs/acs1/pums

2.     Add Tabulate Function

Add the tabulate function ?tabulate= to the API query. This specifies you want to create custom statistics in a table format.

https://api.census.gov/data/2019/acs/acs1/pums?tabulate=

3.     Add Statistical Weight

Add a statistical weight by including weight(insert weight). In this example, we will add weight(PWGTP) to the API query. Including this in the query ensures that results represent the total number of people and not just the number of people in the sample. See the determining which weight to use section of this user guide if you need assistance choosing the desired weight for your dataset.

If you do not include a weight in your API query you will get results for the unweighted counts. This will tell you the sample size that your custom tabulation is based on.

https://api.census.gov/data/2019/acs/acs1/pums?tabulate=weight(PWGTP)

4.     Add Variables to the Rows and/or Columns

Add variables to your table using the predicates &col+ and &row+ to place variables in the columns and rows of your table. In this example, we will add &row+SEX and &row+DIS to provide sex by disability status in the rows of our results. See the “variables” section of the API Discovery Tool for this dataset to explore a list of available variables.

https://api.census.gov/data/2019/acs/acs1/pums?tabulate=weight(PWGTP)&row+SEX&row+DIS

5.     Restrict Your Universe

If you would like to limit your universe, add predicates to restrict your results by variable value. For example, the predicate &HICOV=2 limits results to only include data for the population without health insurance.

https://api.census.gov/data/2019/acs/acs1/pums?tabulate=weight(PWGTP)&row+SEX&row+DIS&HICOV=2

6.     Add Your Geography to the Universe and Table

Add the geography in two places in the API query:

● Add geography to the universe: Use the predicate &for=

● Add geography to the table: Use the predicate &col+for or &row+for

For example, the predicate &for=state:11,24,51 limits results to only include data for DC, Maryland, and Virginia. Add the predicate &col+for to get data broken out for each state in the table. If you do not add a predicate to include “for” in the columns or rows of the table, you will only get data for the combined area of DC, MD, and VA rather than getting data for each state separately.

See the “examples” section of the API Discovery Tool for this dataset to explore the available geographic levels.

https://api.census.gov/data/2019/acs/acs1/pums?tabulate=weight(PWGTP)&col+for&row+SEX&row+DIS&HICOV=2&for=state:11,24,51

7.     View Results

The first row of the API results shows the format of our custom table. In this layout, the first three columns provide data for DC (state=11), MD (state=24) and VA (state=51) respectively. The 4^th column indicates the sex value and the 5^th column indicates the disability code.

[[{"state": "11"}, {"state": "24"}, {"state": "51"},"SEX", "DIS"],

[1591,13598,39616,"1","1"],

[675,8673,25014,"2","1"],

[16761,192542,354846,"1","2"],

[6893,150591,275677,"2","2"]]

The first row of data shows that based on the 2019 ACS 1-Year PUMS, there were approximately 1,591 men with a disability without health insurance in DC, 13,598 in MD, and 39,616 in VA.

8.     Optional: Add Average Function

If you want results calculated as an average instead of totals, add the average function to the API query. For example, add a comma and avg(AGEP) after the weight function to get results for the average age of men and women without health insurance by disability status.

https://api.census.gov/data/2019/acs/acs1/pums?tabulate=weight(PWGTP),avg(AGEP)&col+for&row+SEX&row+DIS&HICOV=2&for=state:11,24,51

[[{"state": "11", "AGEP": "average"}, {"state": "24", "AGEP": "average"}, {"state": "51", "AGEP": "average"},"SEX", "DIS"],

[32,39,43,"1","1"],

[38,49,47,"2","1"],

[34,35,34,"1","2"],

[35,35,34,"2","2"]]

The first row of the data shows that based on the 2019 ACS 1-Year PUMS, the average age for men with a disability that do not have health insurance is approximately 32 in DC, 39 in MD, and 43 in VA.

Use these steps to create API calls that use the wildcard functionality to get results for multiple geographies. For this example, we will find the number of self-employed veterans across all states based on the 2020 CPS ASEC.

https://api.census.gov/data/2020/cps/asec/mar?tabulate=weight(MARSUPWT)&col+PEAFEVER&row+for&for=state:*&SEMP_YN=1

1.      Base API URL

Begin your API queries with the base URL. You can find it in the API Discovery Tool for your dataset. The example below shows the base URL for microdata from the 2020 CPS ASEC.

https://api.census.gov/data/2020/cps/asec/mar

2.     Add Tabulate Function

Add the tabulate function ?tabulate= to the API query. This specifies you want to create custom statistics in a table format.

https://api.census.gov/data/2020/cps/asec/mar?tabulate=

3.     Add Statistical Weight

Add a statistical weight by including weight(insert weight). In this example, we will add weight(MARSUPWT) to the API query. Including this in the query ensures that results represent the total number of people and not just the number of people in the sample. See the determining which weight to use section of this user guide if you need assistance choosing the desired weight for your dataset.

If you do not include a weight in your API query you will get results for the unweighted counts. This will tell you the sample size that your custom tabulation is based on.

https://api.census.gov/data/2020/cps/asec/mar?tabulate=weight(MARSUPWT)

4.     Add Variables to the Rows and/or Columns

Add variables to your table using the predicates &col+ and &row+ to place variables in the columns and rows of your table. In this example, we will add &col+PEAFEVER to provide veteran status in the columns of our results. See the “variables” section of the API Discovery Tool for this dataset to explore a list of available variables.

https://api.census.gov/data/2020/cps/asec/mar?tabulate=weight(MARSUPWT)&col+PEAFEVER

5.     Restrict Your Universe

If you would like to limit your universe, add predicates to restrict your results by variable value. For example, the predicate &SEMP_YN=1 limits the results to only include data for the population that is self-employed.

https://api.census.gov/data/2020/cps/asec/mar?tabulate=weight(MARSUPWT)&col+PEAFEVER&SEMP_YN=1

6.     Add Your Geography to the Universe and Table

Add the geography in two places in the API query:

● Add geography to the universe: Use the predicate &for=

● Add geography to the table: Use the predicate &col+for or &row+for

For example, the predicate &for=state:* uses a wildcard to include data for all states. Add the predicate &row+for to get data broken out for each state in the table. If you do not add a predicate to include “for” in the columns or rows of the table, you will only get data for the combined area covering all states rather than getting data for each state separately.

See the “examples” section of the API Discovery Tool for this dataset to explore the available geographic levels.

https://api.census.gov/data/2020/cps/asec/mar?tabulate=weight(MARSUPWT)&col+PEAFEVER&row+for&SEMP_YN=1&for=state:*

7.     View Results

The first row of the API results tells us the format of our custom table. In this layout, the first three columns provide data for non-veterans (PEAFEVER=2), veterans (PEAFEVER=1), and people not in universe for veteran status (PEAFEVER=-1).  The 4th column indicates the two-digit state code.

[[{"PEAFEVER": "2"}, {"PEAFEVER": "1"}, {"PEAFEVER": "-1"},"state"],

[102606,13940,0,"01"],

[33801,4780,793,"02"],

[277858,16547,0,"04"],

[90825,6489,0,"05"],

….

The first row of the data shows that based on the 2020 CPS ASEC, there were approximately 102,606 self-employed non-veterans and 13,940 self-employed veterans in Alabama. There were not any self-employed individuals who were not-in-universe for veteran status in Alabama.