{"openapi": "3.1.0", "info": {"title": "geocode.net", "description": "US geocoding: forward, reverse, batch, with Census, congressional, state legislative, school district and time zone appends, plus IP geolocation. Results may be stored forever on every plan.", "version": "0.1.0", "x-agents": {"description": "Turn US street addresses into coordinates and back with geocode.net, and attach the Census tract and block group, congressional and state legislative districts, school district and time zone of any address. Also turns a place described in words ('the Amtrak station in Wilmington DE') into an address, and locates an IP address. Use whenever a task needs latitude and longitude for a US address, the address at a coordinate, which district or tract an address is in, or a rough location for an IP, instead of guessing them from memory.", "guide": "Every operation looks something up and changes nothing. Coordinates, districts and tracts are exactly what models get wrong from memory: call geocode.net for them instead.\n\n**Which operation for what**\n\n- An address to coordinates: `geocode`, with `q` as one line, or `street`, `city`, `state` and `postal_code` separately. Add `fields` (`census`, `cd`, `stateleg`, `school`, `timezone`, or `all`) for the tract and block group, congressional and state legislative districts, school district and time zone.\n- Coordinates to an address: `reverse_geocode`. `fields.distance_m` says how far the address is from the point.\n- A place described in words (\"Chiefs Stadium\", \"the Amtrak station in Wilmington DE\"): `resolve_place`. A language model proposes the address and the index checks it; rely on it when `resolved.verified` is true and `resolved.confidence` is high. Slower than `geocode`, and it costs more.\n- Many at once: `geocode_batch` (up to 10,000 addresses) and `reverse_geocode_batch` (up to 10,000 `[lat, lng]` points). Results come back in input order, one unit per item.\n- Where an IP address is: `ip_lookup`.\n\n**Gotchas**\n\n- United States only.\n- Read `accuracy_type` before using a location. `rooftop` and `range_interpolation` are address-level; `street_center`, `place`, `zip`, `county` and `state` are coarser in that order, so never present a ZIP centroid as a house.\n- Through the gateway the API sees the gateway's IP, not your user's, so always pass `ip` to `ip_lookup`. Results are city-level: right for defaults and analytics, wrong for pinpointing a person.\n- A batch costs one unit per item: check `gateway.remaining` before sending a large one.\n- Results may be stored indefinitely on every plan, so keep them rather than looking the same address up twice."}}, "paths": {"/v1/geocode": {"get": {"summary": "Geocode one US address", "description": "Forward geocoding. Returns the best match first with an honest accuracy_type: rooftop (an address point),\nrange_interpolation (placed along the street's house-number range), nearest_rooftop_match, street_center,\nplace, zip, county or state. Results may be stored indefinitely.", "operationId": "geocode", "parameters": [{"name": "q", "in": "query", "required": false, "schema": {"type": "string", "description": "Free-form address, e.g. '1600 Pennsylvania Ave NW, Washington, DC 20500'", "default": "", "title": "Q"}, "description": "Free-form address, e.g. '1600 Pennsylvania Ave NW, Washington, DC 20500'"}, {"name": "street", "in": "query", "required": false, "schema": {"type": "string", "description": "Structured alternative to q: house number and street", "default": "", "title": "Street"}, "description": "Structured alternative to q: house number and street"}, {"name": "city", "in": "query", "required": false, "schema": {"type": "string", "description": "Structured: city", "default": "", "title": "City"}, "description": "Structured: city"}, {"name": "state", "in": "query", "required": false, "schema": {"type": "string", "description": "Structured: two-letter state code", "default": "", "title": "State"}, "description": "Structured: two-letter state code"}, {"name": "postal_code", "in": "query", "required": false, "schema": {"type": "string", "description": "Structured: five-digit ZIP code", "default": "", "title": "Postal Code"}, "description": "Structured: five-digit ZIP code"}, {"name": "fields", "in": "query", "required": false, "schema": {"type": "string", "description": "Comma-separated appends: census, cd, stateleg, school, timezone, or all", "default": "", "title": "Fields"}, "description": "Comma-separated appends: census, cd, stateleg, school, timezone, or all"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "maximum": 10, "minimum": 1, "description": "How many candidates to return, best first", "default": 1, "title": "Limit"}, "description": "How many candidates to return, best first"}], "responses": {"200": {"description": "Successful Response", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GeocodeResponse"}, "example": {"query": "1600 Pennsylvania Ave NW, Washington, DC 20500", "results": [{"formatted": "1600 Pennsylvania Ave NW, Washington, DC 20500", "components": {"number": "1600", "street": "Pennsylvania", "suffix": "Ave", "postdirectional": "NW", "city": "Washington", "county": "District of Columbia", "state": "DC", "zip": "20500", "country": "US"}, "location": {"lat": 38.897675, "lng": -77.036545}, "accuracy": 1.0, "accuracy_type": "rooftop", "source": "nad", "fields": {"census": {"state_fips": "11", "county_fips": "11001", "county": "District of Columbia", "county_subdivision": {"geoid": "1100150000", "name": "Washington city"}, "place": {"geoid": "1150000", "name": "Washington"}, "tract": "11001980000", "block_group": "110019800001", "zcta": "20006", "vintage": "2020 geographies, TIGER/Line 2025"}, "timezone": {"name": "America/New_York", "abbreviation": "EDT", "utc_offset": "-04:00", "utc_offset_seconds": -14400, "observes_dst": true}}}]}}}}, "422": {"description": "Validation Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPValidationError"}}}}}}}, "/v1/resolve": {"get": {"summary": "Describe a place in words; get its address and coordinates", "description": "A language model proposes the most likely US street address for the description and the index verifies it.\nresolved.confidence is the model's own probability that the address is the place you described; resolved.verified\nsays whether the proposed house number exists in the index. results are ordinary geocode results for that address\nwith the usual accuracy_type. Slower than /v1/geocode (one model call, about a second) and metered at more than\none unit; repeat descriptions are answered from a cache. Results may be stored indefinitely.", "operationId": "resolve_place", "parameters": [{"name": "q", "in": "query", "required": false, "schema": {"type": "string", "description": "A description of a place, e.g. 'Chiefs Stadium' or 'the Amtrak station in Wilmington DE'", "default": "", "title": "Q"}, "description": "A description of a place, e.g. 'Chiefs Stadium' or 'the Amtrak station in Wilmington DE'"}, {"name": "fields", "in": "query", "required": false, "schema": {"type": "string", "description": "Comma-separated appends: census, cd, stateleg, school, timezone, or all", "default": "", "title": "Fields"}, "description": "Comma-separated appends: census, cd, stateleg, school, timezone, or all"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "maximum": 10, "minimum": 1, "description": "How many candidates to return, best first", "default": 1, "title": "Limit"}, "description": "How many candidates to return, best first"}], "responses": {"200": {"description": "Successful Response", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResolveResponse"}, "example": {"query": "the Amtrak station in Wilmington DE", "resolved": {"place_name": "Joseph R. Biden Jr. Railroad Station", "address": "100 S French St, Wilmington, DE 19801", "confidence": 0.88, "verified": true, "source": "model", "model": "claude-opus-5-5", "cached": false}, "results": [{"formatted": "100 S French ST, Wilmington, DE 19801", "components": {"number": "100", "predirectional": "S", "street": "French", "suffix": "ST", "city": "Wilmington", "county": "New Castle", "state": "DE", "zip": "19801", "country": "US"}, "location": {"lat": 39.7367, "lng": -75.550995}, "accuracy": 0.9, "accuracy_type": "rooftop", "source": "nad"}]}}}}, "422": {"description": "Validation Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPValidationError"}}}}}}}, "/v1/reverse": {"get": {"summary": "Nearest address to a coordinate", "description": "Reverse geocoding. The nearest address points within about 300 m, else the nearest street, else the containing place.", "operationId": "reverse_geocode", "parameters": [{"name": "lat", "in": "query", "required": true, "schema": {"type": "number", "maximum": 90, "minimum": -90, "description": "Latitude in decimal degrees", "examples": [38.8977], "title": "Lat"}, "description": "Latitude in decimal degrees"}, {"name": "lng", "in": "query", "required": true, "schema": {"type": "number", "maximum": 180, "minimum": -180, "description": "Longitude in decimal degrees", "examples": [-77.0365], "title": "Lng"}, "description": "Longitude in decimal degrees"}, {"name": "fields", "in": "query", "required": false, "schema": {"type": "string", "description": "Comma-separated appends: census, cd, stateleg, school, timezone, or all", "default": "", "title": "Fields"}, "description": "Comma-separated appends: census, cd, stateleg, school, timezone, or all"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "maximum": 10, "minimum": 1, "description": "How many candidates to return, nearest first", "default": 1, "title": "Limit"}, "description": "How many candidates to return, nearest first"}], "responses": {"200": {"description": "Successful Response", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReverseResponse"}, "example": {"query": {"lat": 38.8977, "lng": -77.0365}, "results": [{"formatted": "1600 Pennsylvania Ave NW, Washington, DC 20500", "components": {"number": "1600", "street": "Pennsylvania", "suffix": "Ave", "postdirectional": "NW", "city": "Washington", "county": "District of Columbia", "state": "DC", "zip": "20500", "country": "US"}, "location": {"lat": 38.897675, "lng": -77.036545}, "accuracy": 0.98, "accuracy_type": "rooftop", "source": "nad", "fields": {"distance_m": 4.8}}]}}}}, "422": {"description": "Validation Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPValidationError"}}}}}}}, "/v1/geocode/batch": {"post": {"summary": "Geocode up to 10,000 addresses", "description": "One unit is metered per address. Results come back in the same order as the input. A batch larger than\nwhat is left on your key is refused whole (429 allowance_exceeded) and costs nothing.", "operationId": "geocode_batch", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatchGeocodeRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatchResponse"}, "example": {"results": [{"query": "1600 Pennsylvania Ave NW, Washington, DC 20500", "results": [{"formatted": "1600 Pennsylvania Ave NW, Washington, DC 20500", "components": {"number": "1600", "street": "Pennsylvania", "suffix": "Ave", "postdirectional": "NW", "city": "Washington", "county": "District of Columbia", "state": "DC", "zip": "20500", "country": "US"}, "location": {"lat": 38.897675, "lng": -77.036545}, "accuracy": 1.0, "accuracy_type": "rooftop", "source": "nad"}]}, {"query": "100 S French St, Wilmington, DE 19801", "results": [{"formatted": "100 S French ST, Wilmington, DE 19801", "components": {"number": "100", "predirectional": "S", "street": "French", "suffix": "ST", "city": "Wilmington", "county": "New Castle", "state": "DE", "zip": "19801", "country": "US"}, "location": {"lat": 39.7367, "lng": -75.550995}, "accuracy": 0.9, "accuracy_type": "rooftop", "source": "nad"}]}]}}}}, "422": {"description": "Validation Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPValidationError"}}}}}, "x-mcp-annotations": {"readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false}}}, "/v1/reverse/batch": {"post": {"summary": "Reverse geocode up to 10,000 points", "description": "One unit is metered per point. Results come back in the same order as the input. A batch larger than\nwhat is left on your key is refused whole (429 allowance_exceeded) and costs nothing.", "operationId": "reverse_geocode_batch", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatchReverseRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatchResponse"}, "example": {"results": [{"query": {"lat": 38.8977, "lng": -77.0365}, "results": [{"formatted": "1600 Pennsylvania Ave NW, Washington, DC 20500", "components": {"number": "1600", "street": "Pennsylvania", "suffix": "Ave", "postdirectional": "NW", "city": "Washington", "county": "District of Columbia", "state": "DC", "zip": "20500", "country": "US"}, "location": {"lat": 38.897675, "lng": -77.036545}, "accuracy": 0.98, "accuracy_type": "rooftop", "source": "nad", "fields": {"distance_m": 4.8}}]}, {"query": {"lat": 39.7367, "lng": -75.551}, "results": [{"formatted": "100 S French ST, Wilmington, DE 19801", "components": {"number": "100", "predirectional": "S", "street": "French", "suffix": "ST", "city": "Wilmington", "county": "New Castle", "state": "DE", "zip": "19801", "country": "US"}, "location": {"lat": 39.7367, "lng": -75.550995}, "accuracy": 1.0, "accuracy_type": "rooftop", "source": "nad", "fields": {"distance_m": 0.5}}]}]}}}}, "422": {"description": "Validation Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPValidationError"}}}}}, "x-mcp-annotations": {"readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false}}}, "/v1/ip": {"get": {"summary": "Locate an IP address", "description": "IP geolocation: continent, country, region, city, approximate coordinates, time zone and the country's primary\nlanguages. City-level accuracy, suitable for localisation, defaults and analytics, not for pinpointing a person.\nData: IP Geolocation by DB-IP (db-ip.com), City Lite edition, CC BY 4.0, refreshed monthly. Leave ip empty only\nwhen calling the API directly; through the gateway the API sees the gateway's address, so pass the visitor's ip.", "operationId": "ip_lookup", "parameters": [{"name": "ip", "in": "query", "required": false, "schema": {"type": "string", "description": "IPv4 or IPv6 address. Leave empty for the address the API sees the call from.", "default": "", "title": "Ip"}, "description": "IPv4 or IPv6 address. Leave empty for the address the API sees the call from."}], "responses": {"200": {"description": "Successful Response", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IpResponse"}, "example": {"ip": "8.8.8.8", "continent": {"code": "NA", "name": "North America"}, "country": {"code": "US", "name": "United States", "is_eu": false}, "region": {"name": "California"}, "city": "Mountain View", "location": {"lat": 37.422, "lng": -122.085}, "timezone": {"name": "America/Los_Angeles", "utc_offset": "-07:00"}, "languages": ["en", "es"], "source": "IP Geolocation by DB-IP (https://db-ip.com), CC BY 4.0"}}}}, "422": {"description": "Validation Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPValidationError"}}}}}}}}, "components": {"schemas": {"BatchGeocodeRequest": {"properties": {"addresses": {"items": {"anyOf": [{"type": "string"}, {"$ref": "#/components/schemas/StructuredAddress"}]}, "type": "array", "maxItems": 10000, "title": "Addresses", "description": "One-line addresses, or street/city/state/postal_code objects"}, "fields": {"type": "string", "title": "Fields", "description": "Appends for every address, as in GET /v1/geocode", "default": ""}}, "type": "object", "required": ["addresses"], "title": "BatchGeocodeRequest", "examples": [{"addresses": ["1600 Pennsylvania Ave NW, Washington, DC 20500", "100 S French St, Wilmington, DE 19801"], "fields": ""}]}, "BatchResponse": {"properties": {"results": {"items": {"anyOf": [{"$ref": "#/components/schemas/GeocodeResponse"}, {"$ref": "#/components/schemas/ReverseResponse"}]}, "type": "array", "title": "Results"}}, "type": "object", "required": ["results"], "title": "BatchResponse"}, "BatchReverseRequest": {"properties": {"points": {"items": {"prefixItems": [{"type": "number"}, {"type": "number"}], "type": "array", "maxItems": 2, "minItems": 2}, "type": "array", "maxItems": 10000, "title": "Points", "description": "[lat, lng] pairs"}, "fields": {"type": "string", "title": "Fields", "description": "Appends for every point, as in GET /v1/reverse", "default": ""}}, "type": "object", "required": ["points"], "title": "BatchReverseRequest", "examples": [{"fields": "", "points": [[38.8977, -77.0365], [39.7367, -75.551]]}]}, "Components": {"properties": {"number": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Number"}, "predirectional": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Predirectional"}, "street": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Street"}, "suffix": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Suffix"}, "postdirectional": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Postdirectional"}, "unit": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Unit"}, "city": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "City"}, "county": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "County"}, "state": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "State"}, "zip": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Zip"}, "country": {"type": "string", "title": "Country", "default": "US"}}, "type": "object", "title": "Components"}, "GeocodeResponse": {"properties": {"query": {"type": "string", "title": "Query"}, "results": {"items": {"$ref": "#/components/schemas/Result"}, "type": "array", "title": "Results"}}, "type": "object", "required": ["query", "results"], "title": "GeocodeResponse"}, "HTTPValidationError": {"properties": {"detail": {"items": {"$ref": "#/components/schemas/ValidationError"}, "type": "array", "title": "Detail"}}, "type": "object", "title": "HTTPValidationError"}, "IpCountry": {"properties": {"code": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Code"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Name"}, "is_eu": {"type": "boolean", "title": "Is Eu", "default": false}}, "type": "object", "title": "IpCountry"}, "IpPlace": {"properties": {"code": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Code"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Name"}}, "type": "object", "title": "IpPlace"}, "IpResponse": {"properties": {"ip": {"type": "string", "title": "Ip"}, "continent": {"$ref": "#/components/schemas/IpPlace"}, "country": {"$ref": "#/components/schemas/IpCountry"}, "region": {"anyOf": [{"$ref": "#/components/schemas/IpPlace"}, {"type": "null"}]}, "city": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "City"}, "location": {"$ref": "#/components/schemas/Location"}, "timezone": {"anyOf": [{"$ref": "#/components/schemas/IpTimezone"}, {"type": "null"}]}, "languages": {"items": {"type": "string"}, "type": "array", "title": "Languages", "description": "Primary languages of the country, ISO 639-1"}, "source": {"type": "string", "title": "Source"}}, "type": "object", "required": ["ip", "continent", "country", "location", "source"], "title": "IpResponse"}, "IpTimezone": {"properties": {"name": {"type": "string", "title": "Name"}, "utc_offset": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Utc Offset"}}, "type": "object", "required": ["name"], "title": "IpTimezone"}, "Location": {"properties": {"lat": {"type": "number", "title": "Lat"}, "lng": {"type": "number", "title": "Lng"}}, "type": "object", "required": ["lat", "lng"], "title": "Location"}, "ResolveResponse": {"properties": {"query": {"type": "string", "title": "Query"}, "resolved": {"anyOf": [{"$ref": "#/components/schemas/Resolved"}, {"type": "null"}], "description": "Null when the description could not be turned into a US address"}, "results": {"items": {"$ref": "#/components/schemas/Result"}, "type": "array", "title": "Results", "description": "Ordinary geocode results for the resolved address, best first"}}, "type": "object", "required": ["query", "results"], "title": "ResolveResponse"}, "Resolved": {"properties": {"place_name": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Place Name", "description": "Proper name of the place the model understood, if any"}, "address": {"type": "string", "title": "Address", "description": "The address the model proposed, one line"}, "confidence": {"type": "number", "title": "Confidence", "description": "0 to 1: the model's own probability that this address is the place described"}, "verified": {"type": "boolean", "title": "Verified", "description": "True when the proposed house number exists in the index (rooftop or range_interpolation)"}, "source": {"type": "string", "title": "Source", "description": "Where the address came from; 'model' until a places index exists", "default": "model"}, "model": {"type": "string", "title": "Model"}, "cached": {"type": "boolean", "title": "Cached", "description": "Served from the resolve cache, without a model call"}}, "type": "object", "required": ["address", "confidence", "verified", "model", "cached"], "title": "Resolved"}, "Result": {"properties": {"formatted": {"type": "string", "title": "Formatted", "description": "One-line address as we matched it"}, "components": {"$ref": "#/components/schemas/Components"}, "location": {"$ref": "#/components/schemas/Location"}, "accuracy": {"type": "number", "title": "Accuracy", "description": "0 to 1; see accuracy_type"}, "accuracy_type": {"type": "string", "title": "Accuracy Type", "description": "rooftop | range_interpolation | nearest_rooftop_match | street_center | place | zip | county | state"}, "source": {"type": "string", "title": "Source", "description": "nad | openaddresses | tiger | census"}, "fields": {"anyOf": [{"additionalProperties": true, "type": "object"}, {"type": "null"}], "title": "Fields", "description": "Appends requested with fields="}}, "type": "object", "required": ["formatted", "components", "location", "accuracy", "accuracy_type", "source"], "title": "Result"}, "ReverseResponse": {"properties": {"query": {"$ref": "#/components/schemas/Location"}, "results": {"items": {"$ref": "#/components/schemas/Result"}, "type": "array", "title": "Results"}}, "type": "object", "required": ["query", "results"], "title": "ReverseResponse"}, "StructuredAddress": {"properties": {"street": {"type": "string", "title": "Street", "default": ""}, "city": {"type": "string", "title": "City", "default": ""}, "state": {"type": "string", "title": "State", "default": ""}, "postal_code": {"type": "string", "title": "Postal Code", "default": ""}}, "type": "object", "title": "StructuredAddress"}, "ValidationError": {"properties": {"loc": {"items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, "type": "array", "title": "Location"}, "msg": {"type": "string", "title": "Message"}, "type": {"type": "string", "title": "Error Type"}, "input": {"title": "Input"}, "ctx": {"type": "object", "title": "Context"}}, "type": "object", "required": ["loc", "msg", "type"], "title": "ValidationError"}}, "securitySchemes": {"ApiKey": {"type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your geocode.net key; `Authorization: Bearer <key>` works too. Keys are issued at https://dash.geocode.net/. No key yet? POST https://dash.geocode.net/trial returns a free trial key for agents, with no account, email or card."}}}, "servers": [{"url": "https://api.geocode.net"}], "security": [{"ApiKey": []}]}