{ "openapi": "3.1.0", "info": { "title": "Geoapify Reverse Geocoding API", "version": "1.1.1", "description": "Resolve geographic coordinates to addresses and places." }, "servers": [ { "url": "https://api.geoapify.com/v1", "description": "Default API endpoint." }, { "url": "https://api-eu.geoapify.com/v1", "description": "EU-focused endpoint. Geoapify service processing uses EU infrastructure." } ], "tags": [ { "name": "Reverse Geocoding", "description": "Resolve coordinates to addresses." } ], "paths": { "/geocode/reverse": { "get": { "tags": [ "Reverse Geocoding" ], "operationId": "reverseGeocode", "summary": "Reverse geocode coordinates", "description": "Finds the nearest address or place for geographic coordinates.\n\n- Provide both `lat` and `lon`.\n- Use `type` to request a specific location type.\n- Use `limit` to control the number of returned results.\n\n**Example:** `lat=42.365344&lon=-71.052655`", "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude. Example location: Old Saint Stephens Church, 24 Clark Street, Boston, Massachusetts.", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 42.365344 }, { "name": "lon", "in": "query", "required": true, "description": "Longitude for the same example location.", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -71.052655 }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "type", "in": "query", "required": false, "description": "Requested result type.", "schema": { "type": "string", "enum": [ "country", "state", "city", "postcode", "street", "amenity", "locality", "building" ] } }, { "name": "countrycodes", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country filters.", "schema": { "type": "array", "maxItems": 10, "items": { "type": "string", "enum": [ "ad", "ae", "af", "ag", "ai", "al", "am", "an", "ao", "ap", "aq", "ar", "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg", "bh", "bi", "bj", "bm", "bn", "bo", "br", "bs", "bt", "bv", "bw", "by", "bz", "ca", "cc", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv", "cx", "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec", "ee", "eg", "eh", "er", "es", "et", "eu", "fi", "fj", "fk", "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gs", "gt", "gu", "gw", "gy", "hk", "hm", "hn", "hr", "ht", "hu", "id", "ie", "im", "il", "in", "io", "iq", "ir", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh", "ki", "km", "kn", "kp", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li", "lk", "lr", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me", "mg", "mh", "mk", "ml", "mm", "mn", "mo", "mp", "mq", "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "nf", "ng", "ni", "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk", "pl", "pm", "pr", "ps", "pt", "pw", "py", "qa", "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "sd", "se", "sg", "sh", "si", "sj", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv", "sy", "sz", "tc", "td", "tf", "tg", "th", "tj", "tk", "tm", "tn", "to", "tr", "tt", "tv", "tw", "tz", "ua", "ug", "um", "us", "uy", "uz", "va", "vc", "ve", "vg", "vi", "vn", "vu", "wf", "ws", "ye", "yt", "za", "zm", "zw" ] } } }, { "name": "lang", "in": "query", "required": false, "description": "Result language.", "schema": { "type": "string", "enum": [ "ab", "aa", "af", "ak", "sq", "am", "ar", "an", "hy", "as", "av", "ae", "ay", "az", "bm", "ba", "eu", "be", "bn", "bh", "bi", "bs", "br", "bg", "my", "ca", "ch", "ce", "ny", "zh", "cv", "kw", "co", "cr", "hr", "cs", "da", "dv", "nl", "en", "eo", "et", "ee", "fo", "fj", "fi", "fr", "ff", "gl", "ka", "de", "el", "gn", "gu", "ht", "ha", "he", "hz", "hi", "ho", "hu", "ia", "id", "ie", "ga", "ig", "ik", "io", "is", "it", "iu", "ja", "jv", "kl", "kn", "kr", "ks", "kk", "km", "ki", "rw", "ky", "kv", "kg", "ko", "ku", "kj", "la", "lb", "lg", "li", "ln", "lo", "lt", "lu", "lv", "gv", "mk", "mg", "ms", "ml", "mt", "mi", "mr", "mh", "mn", "na", "nv", "nb", "nd", "ne", "ng", "nn", "no", "ii", "nr", "oc", "oj", "cu", "om", "or", "os", "pa", "pi", "fa", "pl", "ps", "pt", "qu", "rm", "rn", "ro", "ru", "sa", "sc", "sd", "se", "sm", "sg", "sr", "gd", "sn", "si", "sk", "sl", "so", "st", "es", "su", "sw", "ss", "sv", "ta", "te", "tg", "th", "ti", "bo", "tk", "tl", "tn", "to", "tr", "ts", "tt", "tw", "ty", "ug", "uk", "ur", "uz", "ve", "vi", "vo", "wa", "cy", "wo", "fy", "xh", "yi", "yo", "za" ], "default": "en" } }, { "name": "format", "in": "query", "required": false, "description": "Response format.", "schema": { "type": "string", "enum": [ "json", "geojson", "xml" ], "default": "geojson" } } ], "responses": { "200": { "description": "Geocoding results.", "content": { "application/geo+json": { "schema": { "$ref": "#/components/schemas/ReverseGeocodingFeatureCollection" }, "example": { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "datasource": { "sourcename": "openstreetmap", "attribution": "© OpenStreetMap contributors", "license": "Open Database License", "url": "https://www.openstreetmap.org/copyright" }, "name": "Old Saint Stephens Church", "country": "United States", "country_code": "us", "state": "Massachusetts", "county": "Suffolk County", "city": "Boston", "postcode": "02109", "suburb": "North End", "street": "Clark Street", "housenumber": "24", "iso3166_2": "US-MA", "lon": -71.0526773, "lat": 42.3653541, "state_code": "MA", "distance": 0, "result_type": "amenity", "formatted": "Old Saint Stephens Church, 24 Clark Street, Boston, MA 02109, United States of America", "address_line1": "Old Saint Stephens Church", "address_line2": "24 Clark Street, Boston, MA 02109, United States of America", "timezone": { "name": "America/New_York", "offset_STD": "-05:00", "offset_DST": "-04:00", "offset_STD_seconds": -18000, "offset_DST_seconds": -14400, "abbreviation_STD": "EST", "abbreviation_DST": "EDT" }, "plus_code": "87JC9W8W+4W", "plus_code_short": "8W+4W, 02109 Boston, United States", "rank": { "importance": 0.14389741120638372, "popularity": 8.536661234137748 }, "place_id": "51762f9c105fc351c059d17a53ecc32e4540f00102f901ddf3530e00000000c002019203194f6c64205361696e74205374657068656e7320436875726368" }, "geometry": { "type": "Point", "coordinates": [ -71.0526773, 42.3653541 ] }, "bbox": [ -71.0529219, 42.3651972, -71.0524232, 42.365485 ] } ], "query": { "lat": 42.365344, "lon": -71.052655, "plus_code": "87JC9W8W+4W" } } }, "application/json": { "schema": { "$ref": "#/components/schemas/GeocodingJsonResponse" }, "example": { "results": [ { "datasource": { "sourcename": "openstreetmap", "attribution": "© OpenStreetMap contributors", "license": "Open Database License", "url": "https://www.openstreetmap.org/copyright" }, "name": "Old Saint Stephens Church", "country": "United States", "country_code": "us", "state": "Massachusetts", "county": "Suffolk County", "city": "Boston", "postcode": "02109", "suburb": "North End", "street": "Clark Street", "housenumber": "24", "iso3166_2": "US-MA", "lon": -71.0526773, "lat": 42.3653541, "state_code": "MA", "distance": 0, "result_type": "amenity", "formatted": "Old Saint Stephens Church, 24 Clark Street, Boston, MA 02109, United States of America", "address_line1": "Old Saint Stephens Church", "address_line2": "24 Clark Street, Boston, MA 02109, United States of America", "timezone": { "name": "America/New_York", "offset_STD": "-05:00", "offset_DST": "-04:00", "offset_STD_seconds": -18000, "offset_DST_seconds": -14400, "abbreviation_STD": "EST", "abbreviation_DST": "EDT" }, "plus_code": "87JC9W8W+4W", "plus_code_short": "8W+4W, 02109 Boston, United States", "rank": { "importance": 0.14389741120638372, "popularity": 8.536661234137748 }, "place_id": "51762f9c105fc351c059d17a53ecc32e4540f00102f901ddf3530e00000000c002019203194f6c64205361696e74205374657068656e7320436875726368", "bbox": { "lon1": -71.0529219, "lat1": 42.3651972, "lon2": -71.0524232, "lat2": 42.365485 } } ], "query": { "lat": 42.365344, "lon": -71.052655, "plus_code": "87JC9W8W+4W" } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ReverseGeocodingXmlResponse" }, "example": { "results": [ { "datasource": { "sourcename": "openstreetmap", "attribution": "© OpenStreetMap contributors", "license": "Open Database License", "url": "https://www.openstreetmap.org/copyright" }, "name": "Old Saint Stephens Church", "country": "United States", "country_code": "us", "state": "Massachusetts", "county": "Suffolk County", "city": "Boston", "postcode": "02109", "suburb": "North End", "street": "Clark Street", "housenumber": "24", "iso3166_2": "US-MA", "lon": -71.0526773, "lat": 42.3653541, "state_code": "MA", "distance": 0, "result_type": "amenity", "formatted": "Old Saint Stephens Church, 24 Clark Street, Boston, MA 02109, United States of America", "address_line1": "Old Saint Stephens Church", "address_line2": "24 Clark Street, Boston, MA 02109, United States of America", "timezone": { "name": "America/New_York", "offset_STD": "-05:00", "offset_DST": "-04:00", "offset_STD_seconds": -18000, "offset_DST_seconds": -14400, "abbreviation_STD": "EST", "abbreviation_DST": "EDT" }, "plus_code": "87JC9W8W+4W", "plus_code_short": "8W+4W, 02109 Boston, United States", "rank": { "importance": 0.14389741120638372, "popularity": 8.536661234137748 }, "place_id": "51762f9c105fc351c059d17a53ecc32e4540f00102f901ddf3530e00000000c002019203194f6c64205361696e74205374657068656e7320436875726368", "bbox": { "lon1": -71.0529219, "lat1": 42.3651972, "lon2": -71.0524232, "lat2": 42.365485 } } ], "query": { "lat": 42.365344, "lon": -71.052655, "plus_code": "87JC9W8W+4W" } } } } }, "400": { "description": "Missing or invalid reverse geocoding coordinates or parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "statusCode": 400, "error": "Bad Request", "message": "\"lat\" is required" } } } }, "401": { "description": "Missing or invalid Geoapify API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "statusCode": 401, "error": "Unauthorized", "message": "Invalid apiKey" } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "statusCode": 429, "error": "Too Many Requests", "message": "Quota exceeded" } } } }, "500": { "description": "Internal gateway error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "statusCode": 500, "error": "Internal Server Error", "message": "Request failed, please try again later" } } } } } } } }, "components": { "schemas": { "FeatureCollection": { "type": "object", "additionalProperties": true, "required": [ "type", "features" ], "properties": { "type": { "const": "FeatureCollection" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/Feature" } } } }, "Feature": { "type": "object", "additionalProperties": true, "required": [ "type", "properties", "geometry" ], "properties": { "type": { "const": "Feature" }, "properties": { "$ref": "#/components/schemas/GeocodingProperties" }, "geometry": { "oneOf": [ { "$ref": "#/components/schemas/PointGeometry" }, { "$ref": "#/components/schemas/GenericGeometry" }, { "$ref": "#/components/schemas/GeometryCollection" } ] }, "bbox": { "type": "array", "minItems": 4, "maxItems": 6, "items": { "type": "number" } } } }, "PointGeometry": { "type": "object", "required": [ "type", "coordinates" ], "properties": { "type": { "const": "Point" }, "coordinates": { "$ref": "#/components/schemas/Position" } } }, "GenericGeometry": { "type": "object", "additionalProperties": true, "required": [ "type", "coordinates" ], "properties": { "type": { "type": "string", "enum": [ "LineString", "Polygon", "MultiPoint", "MultiLineString", "MultiPolygon" ] }, "coordinates": { "type": "array" } } }, "GeometryCollection": { "type": "object", "required": [ "type", "geometries" ], "properties": { "type": { "const": "GeometryCollection" }, "geometries": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PointGeometry" }, { "$ref": "#/components/schemas/GenericGeometry" }, { "$ref": "#/components/schemas/GeometryCollection" } ] } } } }, "Position": { "type": "array", "minItems": 2, "maxItems": 3, "prefixItems": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "number" } ], "items": false }, "TimezoneOutput": { "type": "object", "required": [ "name", "offset_STD", "offset_DST", "offset_STD_seconds", "offset_DST_seconds" ], "properties": { "name": { "type": "string" }, "name_alt": { "type": "string" }, "country_codes": { "type": "array", "items": { "type": "string" } }, "offset_STD": { "type": "string" }, "offset_DST": { "type": "string" }, "offset_STD_seconds": { "type": "number" }, "offset_DST_seconds": { "type": "number" }, "abbreviation_STD": { "type": "string" }, "abbreviation_DST": { "type": "string" } } }, "PublicDatasource": { "type": "object", "properties": { "sourcename": { "type": "string" }, "attribution": { "type": "string" }, "license": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "PlacesDatasource": { "type": "object", "required": [ "raw" ], "properties": { "sourcename": { "type": "string" }, "attribution": { "type": "string" }, "license": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "raw": { "type": "object", "additionalProperties": true } } }, "GeocodingRank": { "type": "object", "properties": { "confidence": { "type": "number" }, "confidence_city_level": { "type": "number" }, "confidence_street_level": { "type": "number" }, "confidence_building_level": { "type": "number" }, "match_type": { "type": "string", "enum": [ "full_match", "inner_part", "match_by_building", "match_by_street", "match_by_postcode", "match_by_city_or_disrict", "match_by_country_or_state" ] }, "importance": { "type": "number" }, "popularity": { "type": "number" } } }, "WikiPopulation": { "type": "object", "required": [ "actual", "by_years" ], "properties": { "actual": { "type": "string" }, "by_years": { "type": "object", "additionalProperties": { "type": "string" } } } }, "ParsedAddress": { "type": "object", "properties": { "po_box": { "type": "string" }, "unit": { "type": "string" }, "house": { "type": "string" }, "housenumber": { "type": "string" }, "street": { "type": "string" }, "suburb": { "type": "string" }, "postcode": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "state": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" }, "expected_type": { "type": "string", "enum": [ "unknown", "amenity_name", "amenity", "building", "street", "postcode", "suburb", "district", "city", "county", "state", "country" ] } } }, "TextGeocoderQuery": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "plus_code": { "type": "string" }, "text": { "type": "string" }, "postcode": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "housenumber": { "type": "string" }, "street": { "type": "string" }, "parsed": { "$ref": "#/components/schemas/ParsedAddress" }, "categories": { "type": "array", "items": { "type": "object", "required": [ "keys", "label" ], "properties": { "keys": { "type": "array", "items": { "type": "string" } }, "label": { "type": "string" } } } } } }, "ReverseGeocoderQuery": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "plus_code": { "type": "string" }, "text": { "type": "string" }, "postcode": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" } } }, "GeocodingProperties": { "type": "object", "properties": { "name": { "type": "string" }, "continent": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string" }, "region": { "type": "string" }, "state": { "type": "string" }, "state_code": { "type": "string" }, "state_COG": { "type": "string" }, "department_COG": { "type": "string" }, "state_district": { "type": "string" }, "province": { "type": "string" }, "department": { "type": "string" }, "arrondissement": { "type": "string" }, "county": { "type": "string" }, "county_code": { "type": "string" }, "county_district": { "type": "string" }, "city": { "type": "string" }, "city_district": { "type": "string" }, "postcode": { "type": "string" }, "postal_code": { "type": "string" }, "openGeoDB:postal_codes": { "type": "string" }, "district": { "type": "string" }, "suburb": { "type": "string" }, "municipality": { "type": "string" }, "commune": { "type": "string" }, "subdistrict": { "type": "string" }, "city_block": { "type": "string" }, "neighbourhood": { "type": "string" }, "quarter": { "type": "string" }, "section": { "type": "string" }, "sector": { "type": "string" }, "subdivision": { "type": "string" }, "croft": { "type": "string" }, "allotments": { "type": "string" }, "residental": { "type": "string" }, "farm": { "type": "string" }, "farmyard": { "type": "string" }, "industrial": { "type": "string" }, "commercial": { "type": "string" }, "retail": { "type": "string" }, "borough": { "type": "string" }, "town": { "type": "string" }, "township": { "type": "string" }, "village": { "type": "string" }, "hamlet": { "type": "string" }, "locality": { "type": "string" }, "isolated_dwelling": { "type": "string" }, "street": { "type": "string" }, "road": { "type": "string" }, "footway": { "type": "string" }, "pedestrian": { "type": "string" }, "path": { "type": "string" }, "housenumber": { "type": "string" }, "house_number": { "type": "string" }, "house_name": { "type": "string" }, "old_name": { "type": "string" }, "other": { "type": "string" }, "formatted": { "type": "string" }, "address_line1": { "type": "string" }, "address_line2": { "type": "string" }, "unlocode": { "type": "string" }, "iso3166_2": { "type": "string" }, "iso3166_2_sublevel": { "type": "string" }, "iso3166_sublevel": { "type": "string" }, "plus_code": { "type": "string" }, "plus_code_short": { "type": "string" }, "postcodes": { "type": "array", "items": { "type": "string" } }, "other_names": { "type": "object", "additionalProperties": { "type": "string" } }, "population": { "type": "number" }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "parent_as_place_id": { "type": "boolean" }, "timezone": { "$ref": "#/components/schemas/TimezoneOutput" }, "NUTS_3": { "type": "string" }, "result_type": { "type": "string", "enum": [ "unknown", "amenity_name", "amenity", "building", "street", "postcode", "suburb", "district", "city", "county", "state", "country" ] }, "distance": { "type": "number" }, "datasource": { "$ref": "#/components/schemas/PublicDatasource" }, "rank": { "$ref": "#/components/schemas/GeocodingRank" }, "category": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "place_id": { "type": "string", "minLength": 3, "maxLength": 2048 }, "bbox": { "type": "object", "required": [ "lon1", "lat1", "lon2", "lat2" ], "properties": { "lon1": { "type": "number", "minimum": -180, "maximum": 180 }, "lat1": { "type": "number", "minimum": -90, "maximum": 90 }, "lon2": { "type": "number", "minimum": -180, "maximum": 180 }, "lat2": { "type": "number", "minimum": -90, "maximum": 90 } } } } }, "TextGeocodingFeatureCollection": { "allOf": [ { "$ref": "#/components/schemas/FeatureCollection" }, { "type": "object", "properties": { "query": { "$ref": "#/components/schemas/TextGeocoderQuery" } } } ] }, "ReverseGeocodingFeatureCollection": { "allOf": [ { "$ref": "#/components/schemas/FeatureCollection" }, { "type": "object", "required": [ "query" ], "properties": { "query": { "$ref": "#/components/schemas/ReverseGeocoderQuery" } } } ] }, "GeocodingJsonResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/GeocodingProperties" } }, "query": { "anyOf": [ { "$ref": "#/components/schemas/TextGeocoderQuery" }, { "$ref": "#/components/schemas/ReverseGeocoderQuery" } ] } } }, "ForwardGeocodingXmlResponse": { "type": "object", "required": [ "results" ], "xml": { "name": "root" }, "properties": { "results": { "type": "array", "xml": { "name": "results", "wrapped": false }, "items": { "$ref": "#/components/schemas/GeocodingProperties", "xml": { "name": "results" } } }, "query": { "$ref": "#/components/schemas/TextGeocoderQuery", "xml": { "name": "query" } } } }, "ReverseGeocodingXmlResponse": { "type": "object", "required": [ "results" ], "xml": { "name": "root" }, "properties": { "results": { "type": "array", "xml": { "name": "results", "wrapped": false }, "items": { "$ref": "#/components/schemas/GeocodingProperties", "xml": { "name": "results" } } }, "query": { "$ref": "#/components/schemas/ReverseGeocoderQuery", "xml": { "name": "query" } } } }, "AddressAutocompleteXmlResponse": { "type": "object", "required": [ "results" ], "xml": { "name": "root" }, "properties": { "results": { "type": "array", "xml": { "name": "results", "wrapped": false }, "items": { "$ref": "#/components/schemas/GeocodingProperties", "xml": { "name": "results" } } }, "query": { "$ref": "#/components/schemas/TextGeocoderQuery", "xml": { "name": "query" } } } }, "GatewayError": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "description": "HTTP status code returned by the gateway." }, "error": { "type": "string", "description": "Standard HTTP error name." }, "message": { "type": "string", "description": "Human-readable explanation of the error." } } } }, "securitySchemes": { "ApiKeyInQuery": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "Geoapify API key query parameter. Recommended authentication method for public APIs. API keys in URLs can be logged; use x-api-key for server-to-server clients." }, "ApiKeyInHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Geoapify API key header. Supported as an alternative authentication method for public APIs." } } }, "security": [ { "ApiKeyInQuery": [] }, { "ApiKeyInHeader": [] } ] }