zelma

Zelma API

In addition to downloading data files by state or year via our Codebook & Downloads page, users can also use access all Zelma data files through our application programming interface (API).
This API requires no authentication and can be used to pull data into third-party statistics software, such as R, Stata, or Python.

https://zelma.ai/api/data/<version>?[state=<SS>][&year=<YYYY>]

version: Required. Valid versions: 1.1
state: Optional. Valid states: Any two-letter state abbreviation, including DC for the District of Columbia
year: Optional. Valid years: Any year from 1998 to 2023. Many states do not have data for all years, in which case you will receive a 404 response.

Code Examples

You can use one of these examples to load Zelma data into your software of choice, or you can download the data directly by navigating to the relevant zelma.ai/api/data URL in your browser then importing that CSV into your statistics software.

You likely need to increase Stata's request timeout, as the data files may take a long time to download. You can do so with:

. set timeout1 6000

Stata 18+

Users with Stata 18 or after can use the following code to import the Zelma dataset. Similar to Stata < 18 (below), users can specify three parameters for the data: Version number, state, and year. Examples are provided in the following code.

* Example 1 - load all data for Version 1.1.
import delimited "https://zelma.ai/api/data/1.1", varnames(2) rowrange(3:) clear case(preserve)

* Example 2 - load data for all states in 2023.
import delimited "https://zelma.ai/api/data/1.1?year=2023", varnames(2) rowrange(3:) clear case(preserve)

* Example 3 - load all data for Rhode Island. Note that the year parameter is blank.
import delimited "https://zelma.ai/api/data/1.1?state=RI", varnames(2) rowrange(3:) clear case(preserve)

* Example 4 - load 2023 data for Rhode Island.
import delimited "https://zelma.ai/api/data/1.1?year=2023&state=RI", varnames(2) rowrange(3:) clear case(preserve)

Stata < 18

After zelma in the code below, users must specify three ordered parameters:

The Version number. Currently, Zelma is using version 1.1
The state name. Note that users must spell out the full state name, not the two-letter abbreviation. The exception to this is DC, which uses "DC". If users wish to select all states, use "".
The year of interest. If users wish to select all years available, use "". Alternatively, users can select a single year, such as "2023".

do "https://www.zelma.ai/zelma.do"

* Example 1 - load all data for Version 1.1. Note that the state and year parameters
* are blank.
zelma "1.1" "" ""

* Example 2 - load data for all states in 2023. Note that the state parameter is blank.
zelma "1.1" "" "2023"

* Example 3  - load all data for Rhode Island. Note that the year parameter is blank.
zelma "1.1" "Rhode Island" ""

* Example 4  - load 2023 data for Rhode Island.
zelma "1.1" "" ""