AP Elections Map Files API Developer Guide
|
|
|
|
About AP Elections Map Files API
The AP Elections Map Files API provides access to GeoJSON map boundary files used for election coverage. These GeoJSON files are designed to be joined with AP Elections results data and are available for all 50 states and the District of Columbia, beginning in the 2012 election year. For more information, see AP Elections Map Files Reference Guide.
Map File Delivery
Map files are pre-cached as ZIP archives and delivered via presigned Amazon S3 URLs, which provide secure, time-limited access. Presigned URLs expire after one hour. If needed, you can also download individual map files directly using presigned URLs. All API responses are returned in JSON format.
Authentication
All Map Files API methods require a valid API key, which must be passed in the x-api-key request header to authorize access.
Typical Workflows
![Diagram showing the interaction between a user's organization and the AP Elections Map Files API. On the left, a 'Your Organization' box contains 'Users' and an 'Election Results Delivery Application' connected by arrows, with a vertical 'Custom Code” layer between the application and the API. On the right, the 'AP Elections Map Files API' box includes two endpoints: a purple 'Map File ZIP/List' endpoint (api.ap.org/v3/mapfiles[?filelist=true]) and a green 'Map File Download' endpoint (api.ap.org/v3/mapfiles/filename). Numbered arrows (1 and 2) indicate requests from the application through custom code to the API for listing or downloading map files.](assets/images/MapFilesAPI_Workflow.png)
Downloading Map Files in a ZIP Archive
- Use the Map File ZIP/List API method to request a ZIP archive containing map files filtered by criteria such as year and/or resolution. By default, the API returns a ZIP archive containing high-resolution map files from the latest available election year (api.ap.org/v3/mapfiles). Then follow the returned presigned URL to download the pre-cached ZIP file.
Downloading Individual Map Files
- (Optional if you already know the exact file names you want) Use the Map File ZIP/List API method to request links to individual map files by setting filelist=true (api.ap.org/v3/mapfiles?filelist=true). You can optionally filter results by year and/or resolution.
- Use the Map File Download API method to download the selected map files (api.ap.org/v3/mapfiles/filename).
Map File ZIP/List
Returns a presigned URL for downloading a ZIP archive of map files that match the specified filters, such as year and/or resolution. By default, the API returns a ZIP archive containing high-resolution map files from the latest available election year. Optionally, you can request direct download links for the individual map files included in the ZIP archive.
Request
Required Request Header
|
Header |
Description |
Example |
|
x-api-key |
The API key used to authorize the request. |
apikey |
Request URI
|
Method |
Request URI |
|
GET |
https://api.ap.org/{apiVersion}/mapfiles[?OptionalParameters] |
|
|
|
|
The request URI must be URL-encoded. |
|
|
|
|
ImportantRequired Parameter
|
Parameter |
Description |
Valid Value |
|
apiVersion |
The API version. The only valid option for this API method is v3. |
v3 |
Optional Parameters
|
Parameter |
Description |
Default |
Example |
|
year |
Filters files by the year prefix in the file name. Specify all (case-insensitive) to return files from all available election years. Valid values are 2012, 2014, 2016, 2018, 2020, 2022, 2024, 2026, all. |
The latest available election year |
2024 |
|
resolution |
Filters files by resolution based on the file name pattern. Valid values are highres, lowres, all. |
highres |
lowres |
|
filelist |
When set to true, includes a files array in the response containing direct download links for individual map files. Valid values are true and false. |
false |
true |
|
version |
Filters files by version. Valid values are latest or a version number. Only one version may be requested. For more information, see Map File Release Notes. |
latest |
1.2 |
Request URI Example
|
Sample URI |
Returned Results |
|
https://api.ap.org/v3/mapfiles |
A link to download a ZIP archive of high-resolution map files for the latest available election year. |
|
https://api.ap.org/v3/mapfiles?year=2026&resolution=lowres |
A link to download a ZIP archive of low-resolution map files for election year 2026. |
|
https://api.ap.org/v3/mapfiles?year=all&resolution=all |
A link to download a ZIP archive containing both high- and low-resolution map files from all available election years. |
|
https://api.ap.org/v3/mapfiles?year=2026&filelist=true |
Links to download a ZIP archive as well as individual high-resolution map files for election year 2026. |
|
https://api.ap.org/v3/mapfiles?year=2012&version=1.2 |
A link to download a ZIP archive of version 1.2 files for election year 2012. |
Response
On success, returns the standard HTTP status code 200 and response in JSON format. The response contains one or more file download links and metadata.
Data Elements
|
JSON Property |
Description |
|
|
"presignedUrl" |
A presigned URL for downloading a ZIP archive of map files that match the specified filters. |
|
|
"version" |
The requested map file version (latest or a specific version number). |
|
|
"year" |
The election year associated with the map files. |
|
|
"resolution" |
The map resolution (highres, lowres or all). |
|
|
"fileCount" |
The number of map files that match the specified filters. |
|
|
"sizeBytes" |
The size of the ZIP archive, in bytes. |
|
|
"generatedAt" |
The date and time when the ZIP archive was generated. |
|
|
"expiresAt" |
The date and time when the presigned URL to the ZIP archive expires. |
|
|
"cached" |
Indicates whether the ZIP file is cached (true) or not (false). |
|
|
"timestamp" |
The date and time when the request was submitted. |
|
|
"files" |
(Returned only when filelist is set to true) A container for links to individual map files. |
|
|
"name" |
The map file name. |
|
|
"year" |
The folder location of the map file within the ZIP archive. |
|
|
"version" |
The requested map file version (latest or a specific version number). |
|
|
"url" |
A presigned Amazon S3 URL for downloading the map file (expires after one hour). |
|
|
"releaseDate" |
|
The date when the AP released this version of the map file. |
Sample Response (200 – Cache Available)
|
{ |
Sample Response (200 – with filelist=true)
|
{ |
Map File Download
Downloads an individual GeoJSON map file. You can download the latest version of the file by default or request a specific version of the file. The API returns the HTTP status code of 302 and redirects to a presigned Amazon S3 URL in the Location response header.
Your client application follows the redirect and downloads the file directly from S3. Individual file downloads are not cached; they are served directly from S3 via a presigned URL on each request.
Request
Required Request Header
|
Header |
Description |
Example |
|
x-api-key |
The API key used to authorize the request. |
apikey |
Request URI
|
Method |
Request URI |
|
GET |
https://api.ap.org/{version}/mapfiles/{filename} |
|
|
|
|
The request URI must be URL-encoded. |
|
|
|
|
Required Parameters
|
Parameter |
Description |
Example |
|
apiVersion |
The API version. The only valid option for this API method is v3. |
v3 |
|
filename |
GeoJSON filename. The file extension must be .geojson. |
2026-cd-county-highres.geojson |
Optional Parameter
|
Parameter |
Description |
Example |
|
version |
Requests a specific version of the file. Valid values are latest (the default) or a version number. Only one version may be requested. |
1.2 |
Request URI Examples
https://api.ap.org/v3/mapfiles/2026-cd-county-highres.geojson
https://api.ap.org/v3/mapfiles/2026-cd-county-lowres.geojson?version=1.2
Response
Response (302 – Redirect)
On success, the API returns the standard HTTP status code 302 and redirects to a presigned Amazon S3 URL. Your client application's HTTP library automatically follows the redirect and downloads the file. If the version parameter was added to the request, the API returns the specified version of the file.
Response Headers
|
Header |
Description |
|
|
Location |
Presigned Amazon S3 download URL (expires after one hour). |
|
|
X-RateLimit-* |
Quota and rate-limit headers. |
Response (404 – Not Found)
|
{ |
Response (400 – Invalid File Format)
|
{ |