{ "openapi": "3.1.0", "info": { "title": "Geoapify Place Details API", "version": "0.1.0", "description": "OpenAPI specification for retrieving details and related feature groups for a place." }, "servers": [ { "url": "https://api.geoapify.com/v2" } ], "tags": [ { "name": "Place Details", "description": "Retrieve details and related feature groups for a place." } ], "paths": { "/place-details": { "get": { "tags": [ "Place Details" ], "operationId": "getPlaceDetails", "summary": "Get place details", "description": "Get details for a Geoapify place. Provide a place id, or provide lat and lon with optional OSM identifiers.", "parameters": [ { "name": "apiKey", "in": "query", "required": true, "description": "Geoapify API key.", "schema": { "type": "string" }, "example": "YOUR_API_KEY" }, { "name": "id", "in": "query", "required": false, "description": "Geoapify place identifier returned by Geoapify APIs.", "schema": { "type": "string", "minLength": 3, "maxLength": 2048 } }, { "name": "lat", "in": "query", "required": false, "description": "Place latitude. Must be used together with lon when id is not provided.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": false, "description": "Place longitude. Must be used together with lat when id is not provided.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "osm_id", "in": "query", "required": false, "description": "OpenStreetMap object identifier.", "schema": { "type": "number" }, "example": 240109189 }, { "name": "osm_type", "in": "query", "required": false, "description": "OpenStreetMap object type.", "schema": { "type": "string", "enum": [ "r", "w", "n" ] }, "example": "w" }, { "name": "features", "in": "query", "required": false, "description": "Requested place detail feature groups. Multiple values can be comma-separated, repeated, or separated with |. Defaults to details.", "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "default": [ "details" ], "items": { "type": "string", "pattern": "^((feature):)?[a-z\\.0-9_-]{5,100}(,[a-z\\.0-9_-]{5,100})*$" } }, "examples": { "defaultDetails": { "summary": "Details", "value": [ "details" ] }, "detailsAndRadius": { "summary": "Details and nearby places", "value": [ "details,radius_500" ] }, "commute": { "summary": "Walking and driving areas", "value": [ "walk_10|drive_15" ] } } }, { "name": "lang", "in": "query", "required": false, "description": "Result language as a supported two-letter language code.", "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" }, "example": "en" } ], "responses": { "200": { "description": "Place details result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceDetailsFeatureCollection" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid Geoapify API key." }, "429": { "description": "Rate limit or quota exceeded." }, "500": { "description": "Internal gateway error." } } } } }, "components": { "schemas": { "PlaceDetailsFeatureCollection": { "type": "object", "additionalProperties": false, "required": [ "type", "features" ], "properties": { "type": { "const": "FeatureCollection" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/PlaceDetailsFeature" } } } }, "PlaceDetailsFeature": { "type": "object", "additionalProperties": false, "required": [ "type", "properties", "geometry" ], "properties": { "type": { "const": "Feature" }, "properties": { "$ref": "#/components/schemas/PlaceDetailsProperties" }, "geometry": { "$ref": "#/components/schemas/GeoJsonGeometry" }, "bbox": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number" } } } }, "PlaceDetailsProperties": { "type": "object", "additionalProperties": true, "properties": { "place_id": { "type": "string", "description": "Geoapify place identifier." }, "feature_type": { "type": "string", "description": "Returned feature group." }, "name": { "type": "string" }, "formatted": { "type": "string" }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "datasource": { "$ref": "#/components/schemas/Datasource" }, "datasources": { "type": "array", "items": { "$ref": "#/components/schemas/Datasource" } } } }, "Datasource": { "type": "object", "additionalProperties": true, "properties": { "sourcename": { "type": "string" }, "attribution": { "type": "string" }, "license": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "GeoJsonGeometry": { "oneOf": [ { "$ref": "#/components/schemas/PointGeometry" }, { "$ref": "#/components/schemas/LineStringGeometry" }, { "$ref": "#/components/schemas/PolygonGeometry" }, { "$ref": "#/components/schemas/MultiPointGeometry" }, { "$ref": "#/components/schemas/MultiLineStringGeometry" }, { "$ref": "#/components/schemas/MultiPolygonGeometry" } ] }, "PointGeometry": { "type": "object", "additionalProperties": false, "required": [ "type", "coordinates" ], "properties": { "type": { "const": "Point" }, "coordinates": { "$ref": "#/components/schemas/Position" } } }, "LineStringGeometry": { "type": "object", "additionalProperties": false, "required": [ "type", "coordinates" ], "properties": { "type": { "const": "LineString" }, "coordinates": { "type": "array", "minItems": 2, "items": { "$ref": "#/components/schemas/Position" } } } }, "PolygonGeometry": { "type": "object", "additionalProperties": false, "required": [ "type", "coordinates" ], "properties": { "type": { "const": "Polygon" }, "coordinates": { "type": "array", "items": { "type": "array", "minItems": 4, "items": { "$ref": "#/components/schemas/Position" } } } } }, "MultiPointGeometry": { "type": "object", "additionalProperties": false, "required": [ "type", "coordinates" ], "properties": { "type": { "const": "MultiPoint" }, "coordinates": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } } } }, "MultiLineStringGeometry": { "type": "object", "additionalProperties": false, "required": [ "type", "coordinates" ], "properties": { "type": { "const": "MultiLineString" }, "coordinates": { "type": "array", "items": { "type": "array", "minItems": 2, "items": { "$ref": "#/components/schemas/Position" } } } } }, "MultiPolygonGeometry": { "type": "object", "additionalProperties": false, "required": [ "type", "coordinates" ], "properties": { "type": { "const": "MultiPolygon" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "minItems": 4, "items": { "$ref": "#/components/schemas/Position" } } } } } }, "Position": { "type": "array", "minItems": 2, "maxItems": 3, "prefixItems": [ { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude." }, { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude." }, { "type": "number", "description": "Optional altitude." } ], "items": false } } } }