{ "openapi": "3.1.0", "info": { "title": "Geocoding API", "version": "1.0.0", "description": "Place names to coordinates and back for 235,640 cities and towns worldwide, no third-party calls.\n\nCity and place-level forward and reverse geocoding for 235,640 populated places worldwide, self-hosted from GeoNames and refreshed daily: turn a place name into coordinates (population-ranked, with exact, prefix and alternate-name matching for local and historical names like Firenze or Bombay) or coordinates into the nearest places with distances. Every result carries the GeoNames id, region, population, timezone and place type (capital, admin seat, neighbourhood). No third-party calls at request time.", "contact": { "name": "Data and APIs", "url": "https://dataandapis.com/contact" }, "termsOfService": "https://dataandapis.com/terms-of-service", "license": { "name": "Data and APIs Terms of Service", "url": "https://dataandapis.com/terms-of-service" }, "x-logo": { "url": "https://dataandapis.com/images/geocoding.webp" } }, "externalDocs": { "description": "Documentation, live tester and pricing", "url": "https://dataandapis.com/apis/geocoding" }, "servers": [ { "url": "https://api-geocoding.dataandapis.com" } ], "tags": [ { "name": "Data", "description": "Geocoding API belongs to the Data category of the Data and APIs catalog." } ], "paths": { "/v1/sources": { "get": { "operationId": "dataSources", "summary": "Data Sources", "description": "Data Sources endpoint of the Geocoding API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/geocoding/data-sources" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "sources": [ { "slug": "geonames-cities500", "name": "GeoNames cities500", "url": "https://download.geonames.org/export/dump/cities500.zip", "license": "CC BY 4.0", "cadence": "daily modifications sync (shared geography database)", "places": 235640, "last_update": "2026-09-02 21:41:55" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/geocode": { "get": { "operationId": "forwardGeocode", "summary": "Forward Geocode", "description": "Forward Geocode endpoint of the Geocoding API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/geocoding/forward-geocode" }, "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "5" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Paris" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "query": "Paris", "count": 5, "results": [ { "id": 2988507, "name": "Paris", "ascii_name": "Paris", "latitude": 48.85341, "longitude": 2.3488, "country": "FR", "admin1": "Île-de-France", "admin1_code": "11", "population": 2138551, "timezone": "Europe/Paris", "feature_code": "PPLC", "place_type": "national capital", "is_capital": true, "matched_by": "exact" }, { "id": 4717560, "name": "Paris", "ascii_name": "Paris", "latitude": 33.66094, "longitude": -95.55551, "country": "US", "admin1": "Texas", "admin1_code": "TX", "population": 24782, "timezone": "America/Chicago", "feature_code": "PPLA2", "place_type": "second-order admin seat", "is_capital": false, "matched_by": "exact" }, { "id": 6942553, "name": "Paris", "ascii_name": "Paris", "latitude": 43.2, "longitude": -80.38333, "country": "CA", "admin1": "Ontario", "admin1_code": "08", "population": 12310, "timezone": "America/Toronto", "feature_code": "PPL", "place_type": "populated place", "is_capital": false, "matched_by": "exact" } ], "source": "GeoNames cities500 (CC BY 4.0)", "source_url": "https://www.geonames.org/", "scope": "city/place-level geocoding (populated places with population >= 500)" } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/place/{id}": { "get": { "operationId": "placeDetail", "summary": "Place Detail", "description": "Place Detail endpoint of the Geocoding API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/geocoding/place-detail" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2988507" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "id": 2988507, "name": "Paris", "ascii_name": "Paris", "latitude": 48.85341, "longitude": 2.3488, "country": "FR", "admin1": "Île-de-France", "admin1_code": "11", "population": 2138551, "timezone": "Europe/Paris", "feature_code": "PPLC", "place_type": "national capital", "is_capital": true, "elevation_m": 42, "alternate_names": [ "Baariis", "Bahliz", "Baris", "Bariz", "Lungsod ng Paris", "Lutece", "Lutetia", "Lutetia Parisorum", "Lutèce", "PAR", "Pa-ri", "Paarys", "Palika", "Paname", "Pantruche", "Paraeis", "Paras", "Pari", "Paries", "Parigge", "Pariggi", "Parighji", "Parigi", "Pariis", "Pariisi" ], "source": "GeoNames cities500 (CC BY 4.0)", "source_url": "https://www.geonames.org/", "scope": "city/place-level geocoding (populated places with population >= 500)" } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/reverse": { "get": { "operationId": "reverseGeocode", "summary": "Reverse Geocode", "description": "Reverse Geocode endpoint of the Geocoding API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/geocoding/reverse-geocode" }, "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "string" }, "example": "40.71" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3" }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "string" }, "example": "-74.0" }, { "name": "min_population", "in": "query", "required": false, "schema": { "type": "string" }, "example": "0" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "latitude": 40.71, "longitude": -74, "search_radius_deg": 0.25, "count": 3, "results": [ { "id": 5128581, "name": "New York City", "ascii_name": "New York City", "latitude": 40.71427, "longitude": -74.00597, "country": "US", "admin1": "New York", "admin1_code": "NY", "population": 8804190, "timezone": "America/New_York", "feature_code": "PPL", "place_type": "populated place", "is_capital": false, "distance_km": 0.7 }, { "id": 8436473, "name": "Financial District", "ascii_name": "Financial District", "latitude": 40.70789, "longitude": -74.00857, "country": "US", "admin1": "New York", "admin1_code": "NY", "population": 60976, "timezone": "America/New_York", "feature_code": "PPLX", "place_type": "section of populated place", "is_capital": false, "distance_km": 0.8 }, { "id": 5112540, "name": "Chinatown", "ascii_name": "Chinatown", "latitude": 40.71649, "longitude": -73.99625, "country": "US", "admin1": "New York", "admin1_code": "NY", "population": 90000, "timezone": "America/New_York", "feature_code": "PPLX", "place_type": "section of populated place", "is_capital": false, "distance_km": 0.8 } ], "source": "GeoNames cities500 (CC BY 4.0)", "source_url": "https://www.geonames.org/", "scope": "city/place-level geocoding (populated places with population >= 500)" } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 2 tokens per call." } } }, "security": [ { "ApiKey": [] } ] }