1. Documentation
2. API
3. Precincts
4. List

Listing Precincts

Get a list of Precinct. By default, we return a paginated list all precincts across all elections, which problaby isn't very useful to you, so you probably want to include some query parameters to filter the list for the precincts you actually want.

HTTP Request

GET /v1/precincts

Examples

Get a list of all Precincts:

https://api.ballotapi.org/v1/precincts

Get a list of Precincts for a specific election:

https://api.ballotapi.org/v1/precincts?elections=1238es8f

Get a list of Precincts for a specific contest:

https://api.ballotapi.org/v1/precincts?contests=3094ur4u2e

Get a district map (i.e. merged geometry of the precinct list) for a specific contest:

https://api.ballotapi.org/v1/precincts?contests=3094ur4u2e&extra=merge_geos

Query Parameters

Merge Geometries

If you include the extra=merge_geos query parameter in your request, we will merge all of the areas of the resulting precincts and return that merged geometry as a GeoJSON object in the extra results parameter. This is useful for generating district maps.

Example merged geometry result:

{
    "type": "response",
    "data": [...],
    "next": "...",
    "extra": {
        "merge_geos": {
            "type": "MultiPolygon",
            ...
        },
    },
    "timestamp": "...",
    "url": "..."
}

NOTE: We merge the results of all the Precinct results for your request, not just the precincts shown on the first page of results. That way, you don't need to page through the results to get a full district map. If you don't want to merge all of the results, use the ids query parameter to specify exactly what precincts you want us to merge.

NOTE: In the next results parameter we do not inlcude the merge_geos parameter. So if you start paging through the precint results, you'll only see the merged geometry on the first page. We do this so we're not generating full district maps on every page request.

Response

We will return the results of your request as a Response object with the data attribute as the list of Precincts.

Responses can be paginated! Be sure to check the next attribute for the next page of data.

Example response:

{
    "type": "response",
    "data": [
        {
            "type": "precinct",
            "id": "345-6",
            "ocd_id": null,
            "election_id": "123-4",
            "voting_info": {...},
            "geo": {...},
        },
        ...
    ],
    "next": "https://api.ballotapi.org/...",
    "extra": {},
    "timestamp": "2018-01-01T00:00:00+00:00",
    "url": "https://api.ballotapi.org/..."
}

HTTP Response Codes