Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/geocodio:geocodio-lists-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Geocodio Lists API
description: 'Geocodio''s RESTful API allows you to perform forward and reverse geocoding lookups. We support both batch requests as well as individual lookups.
You can also optionally ask for data appends such as timezone, Congressional districts or similar things of that nature.'
termsOfService: https://www.geocod.io/terms-of-use/
license:
name: Geocodio Terms of Use
url: https://www.geocod.io/terms-of-use/
contact:
email: hello@geocod.io
version: '2.0'
servers:
- url: https://api.geocod.io/v2
description: Self-Serve Geocodio API Endpoint
- url: https://api.enterprise.geocod.io/v2
description: Geocodio API Endpoint for Enterprise Customers
tags:
- name: Lists
description: Upload and manage spreadsheets for batch geocoding
paths:
/lists:
get:
tags:
- Lists
summary: List uploaded spreadsheets
operationId: listsList
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
description: Page number for pagination
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListsCollection'
examples:
basic:
summary: List uploaded spreadsheets for the current user
value:
current_page: 1
current_page_url: https://api.geocodio.dev/v2/lists?page=1
data:
- id: 148
fields: []
file:
estimated_rows_count: 4050
filename: illum-nisi-voluptatem-voluptatem.csv
status:
state: COMPLETED
progress: 100
message: Completed
time_left_description: null
time_left_seconds: null
download_url: https://api.geocodio.dev/v2/lists/148/download
expires_at: '2026-06-07T16:07:39.000000Z'
- id: 147
fields: []
file:
estimated_rows_count: 3364
filename: quo-optio-autem-dolor.csv
status:
state: COMPLETED
progress: 100
message: Completed
time_left_description: null
time_left_seconds: null
download_url: https://api.geocodio.dev/v2/lists/147/download
expires_at: '2026-06-07T16:07:39.000000Z'
first_page_url: https://api.geocodio.dev/v2/lists?page=1
from: 1
next_page_url: null
path: https://api.geocodio.dev/v2/lists
per_page: 15
prev_page_url: null
to: 2
with-warnings:
summary: Listing spreadsheets with a malformed fields parameter -- the response carries a _warnings array
value:
current_page: 1
current_page_url: https://api.geocodio.dev/v2/lists?page=1
data:
- id: 872
fields: []
file:
estimated_rows_count: 3879
filename: blanditiis-sunt-est-placeat-dolores.csv
status:
state: COMPLETED
progress: 100
message: Completed
time_left_description: null
time_left_seconds: null
download_url: https://api.geocodio.dev/v2/lists/872/download
expires_at: '2026-09-28T17:37:35.000000Z'
- id: 871
fields: []
file:
estimated_rows_count: 3562
filename: aut-voluptatem-commodi-aut.csv
status:
state: COMPLETED
progress: 100
message: Completed
time_left_description: null
time_left_seconds: null
download_url: https://api.geocodio.dev/v2/lists/871/download
expires_at: '2026-09-28T17:37:35.000000Z'
first_page_url: https://api.geocodio.dev/v2/lists?page=1
from: 1
next_page_url: null
path: https://api.geocodio.dev/v2/lists
per_page: 15
prev_page_url: null
to: 2
_warnings:
- The fields parameter should contain a comma-separated list of fields instead of an array
'403':
description: Invalid API key, or feature not available.
security:
- geocodioApiKey: []
post:
tags:
- Lists
summary: Upload spreadsheet for geocoding
operationId: listsCreate
parameters:
- name: fields
in: query
description: Comma-separated list of data append fields. See the enum for valid values.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- cd113
- cd114
- cd115
- cd116
- cd117
- cd118
- cd119
- cd120
- cd
- census2000
- census2010
- census2011
- census2012
- census2013
- census2014
- census2015
- census2016
- census2017
- census2018
- census2019
- census2020
- census2021
- census2022
- census2023
- census2024
- census2025
- census
- stateleg
- stateleg-next
- school
- ffiec
- zip4
- acs-demographics
- acs-demographics-block_group
- acs-demographics-tract
- acs-demographics-zcta
- acs-demographics-place
- acs-demographics-msa
- acs-demographics-county
- acs-demographics-county_subdivision
- acs-demographics-state
- acs-demographics-division
- acs-demographics-region
- acs-demographics-nation
- acs-economics
- acs-economics-block_group
- acs-economics-tract
- acs-economics-zcta
- acs-economics-place
- acs-economics-msa
- acs-economics-county
- acs-economics-county_subdivision
- acs-economics-state
- acs-economics-division
- acs-economics-region
- acs-economics-nation
- acs-families
- acs-families-block_group
- acs-families-tract
- acs-families-zcta
- acs-families-place
- acs-families-msa
- acs-families-county
- acs-families-county_subdivision
- acs-families-state
- acs-families-division
- acs-families-region
- acs-families-nation
- acs-housing
- acs-housing-block_group
- acs-housing-tract
- acs-housing-zcta
- acs-housing-place
- acs-housing-msa
- acs-housing-county
- acs-housing-county_subdivision
- acs-housing-state
- acs-housing-division
- acs-housing-region
- acs-housing-nation
- acs-social
- acs-social-block_group
- acs-social-tract
- acs-social-zcta
- acs-social-place
- acs-social-msa
- acs-social-county
- acs-social-county_subdivision
- acs-social-state
- acs-social-division
- acs-social-region
- acs-social-nation
- riding
- riding-next
- provriding
- provriding-next
- statcan
- uk-westminster
- uk-westminster-next
- uk-devolved
- uk-devolved-next
- uk-local
- uk-local-next
- uk-census
- timezone
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- direction
- format
properties:
file:
type: string
format: binary
description: Spreadsheet file (csv, xlsx, xls)
direction:
type: string
enum:
- forward
- reverse
format:
type: string
description: Column format template, e.g. "{{A}} {{B}} {{C}}"
callback:
type: string
format: uri
description: Optional webhook URL invoked when processing completes
application/json:
schema:
type: object
required:
- direction
- format
- file
- filename
properties:
file:
type: string
description: Inline file contents as a string
filename:
type: string
description: Filename for the inline content
direction:
type: string
enum:
- forward
- reverse
format:
type: string
description: Column format template, e.g. "{{A}} {{B}} {{C}}"
callback:
type: string
format: uri
required: true
description: Multipart upload with a spreadsheet file, or JSON body with inline file contents
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJobCreated'
examples:
basic:
summary: Upload a spreadsheet inline for forward geocoding
value:
id: 146
file:
headers:
- address
estimated_rows_count: 2
filename: example.csv
with-warnings:
summary: Uploading a spreadsheet against a superseded API version -- the response carries a _warnings array
value:
id: 870
file:
headers:
- address
estimated_rows_count: 2
filename: example.csv
_warnings:
- 'There is a newer API version available, please consider upgrading to v2. See changelog here: https://www.geocod.io/docs/#changelog'
'400':
description: Invalid request.
'403':
description: Invalid API key, or feature not available.
security:
- geocodioApiKey: []
/lists/{id}:
get:
tags:
- Lists
summary: Get list processing status
operationId: listsStatus
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
examples:
basic:
summary: Get status of an uploaded spreadsheet
value:
id: 149
fields: []
file:
estimated_rows_count: 1042
filename: mollitia-dolore-nihil.csv
status:
state: COMPLETED
progress: 100
message: Completed
time_left_description: null
time_left_seconds: null
download_url: https://api.geocodio.dev/v2/lists/149/download
expires_at: '2026-06-07T16:07:39.000000Z'
with-warnings:
summary: Spreadsheet status with a malformed fields parameter -- the response carries a _warnings array
value:
id: 873
fields: []
file:
estimated_rows_count: 253
filename: perferendis-aut-nobis-necessitatibus.csv
status:
state: COMPLETED
progress: 100
message: Completed
time_left_description: null
time_left_seconds: null
download_url: https://api.geocodio.dev/v2/lists/873/download
expires_at: '2026-09-28T17:37:35.000000Z'
_warnings:
- The fields parameter should contain a comma-separated list of fields instead of an array
'404':
description: Resource not found.
'403':
description: Invalid API key, or feature not available.
security:
- geocodioApiKey: []
delete:
tags:
- Lists
summary: Delete a list
operationId: listsDelete
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: List deleted successfully.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
_warnings:
$ref: '#/components/schemas/Warnings'
'404':
description: Resource not found.
'424':
description: Operation cannot be completed (dependency failed).
'403':
description: Invalid API key, or feature not available.
security:
- geocodioApiKey: []
/lists/{id}/download:
get:
tags:
- Lists
summary: Download list results
operationId: listsDownload
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: 'Geocoded spreadsheet file. Format matches the uploaded spreadsheet (CSV, XLSX, or XLS). If the list is still processing or the file has expired, the response is a JSON message with success: false.'
content:
text/csv:
schema:
type: string
format: binary
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
schema:
type: string
format: binary
application/vnd.ms-excel:
schema:
type: string
format: binary
application/json:
schema:
type: object
properties:
message:
type: string
success:
type: boolean
_warnings:
$ref: '#/components/schemas/Warnings'
'400':
description: Invalid request.
'404':
description: Resource not found.
'403':
description: Invalid API key, or feature not available.
security:
- geocodioApiKey: []
components:
schemas:
ImportJobStatus:
type: object
properties:
state:
type: string
progress:
type: integer
message:
type: string
time_left_description:
type:
- string
- 'null'
time_left_seconds:
type:
- string
- 'null'
File:
type: object
properties:
headers:
type: array
items:
type: string
estimated_rows_count:
type: integer
filename:
type: string
ImportJobCreated:
type: object
properties:
id:
type: integer
file:
$ref: '#/components/schemas/File'
_warnings:
$ref: '#/components/schemas/Warnings'
Warnings:
type: array
items:
type: string
description: Non-fatal advisories about the request — an unrecognized parameter or field name, a superseded API version, or an append that was skipped. Present only when at least one warning was raised.
ImportFileMetadata:
type: object
properties:
estimated_rows_count:
type: integer
filename:
type: string
ListsCollection:
type: object
properties:
current_page:
type: integer
current_page_url:
type: string
data:
type: array
items:
$ref: '#/components/schemas/ImportJob'
first_page_url:
type: string
from:
type: integer
next_page_url:
type:
- string
- 'null'
path:
type: string
per_page:
type: integer
prev_page_url:
type:
- string
- 'null'
to:
type: integer
_warnings:
$ref: '#/components/schemas/Warnings'
ImportJob:
type: object
properties:
id:
type: integer
fields:
type: array
items:
type: string
file:
$ref: '#/components/schemas/ImportFileMetadata'
status:
$ref: '#/components/schemas/ImportJobStatus'
download_url:
type: string
expires_at:
type: string
_warnings:
$ref: '#/components/schemas/Warnings'
securitySchemes:
geocodioApiKey:
type: apiKey
name: api_key
in: query
externalDocs:
description: Find out more about Geocodio
url: https://www.geocod.io
x-provenance:
method: harvested
publisher: Geocodio
source: https://api.geocod.io/openapi-spec.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)