Data dictionaries

One dictionary for each kind of record the API returns. Each lists every field with its type, whether it is always present, whether it can be null, its format, what it means, the values a coded field takes and an example from real data, and says how the record connects to the others and what to watch for.

The dictionaries are built from the same description as /openapi.json and the API reference, so they always match what the API returns. Examples come from the sample data; what each coded value means is on Field values.

Download as CSV Download as JSON

The CSV has one row per field: record, field, type, always_present, nullable, format, description, values, value_set, example and where (which responses have it, when not all do). The JSON has the same, grouped by record, with each record’s endpoints, relations and notes.

Records

Reading a dictionary

Field

The field’s path from the record. details.all_mail is all_mail inside details; choices[].id is the id of each item in the choices array.

Type

string, integer, number, boolean, object or an array of one of them, or another record (a link to its dictionary). or null means the value can be null; optional means the key itself is present only when it applies, as in details. Every other field is always present.

Format

How a string is written: dates are YYYY-MM-DD, times are ISO 8601 with a time zone, and URLs are absolute. Amounts are in U.S. dollars and percentages run from 0 to 100, as each field says.

Values

For a coded field, the values it takes, linked to their meanings on Field values. Open sets come from election offices’ own classifications and can gain values.

Example

A real value from the sample data, or from the reference’s example where no sample has one.

Election export (CSV)

GET /v1/elections/{slug}/export?format=csv has one row per endorsement (per endorser and choice, so a ranked-choice ranking is a row per rank), each repeating its election, contest, district and choice. Contests no one endorsed in have no rows; the JSON export has every contest. An empty cell is a null or a missing value: no candidate on a measure, no result yet.