{ "openapi": "3.1.0", "info": { "title": "Geoapify Postcode API", "version": "0.1.0", "description": "OpenAPI specification for Geoapify postcode search and autocomplete endpoints." }, "servers": [ { "url": "https://api.geoapify.com/v1" } ], "tags": [ { "name": "Postcode", "description": "Search and list postcode results." } ], "paths": { "/postcode/search": { "get": { "tags": [ "Postcode" ], "operationId": "searchPostcodes", "summary": "Search postcodes", "description": "Search for postcode features by postcode text, or reverse-search by latitude and longitude. Provide either postcode or both lat and lon. Do not combine postcode with lat or lon.", "parameters": [ { "name": "apiKey", "in": "query", "required": true, "description": "Geoapify API key.", "schema": { "type": "string" }, "example": "YOUR_API_KEY" }, { "name": "postcode", "in": "query", "required": false, "description": "Postcode text to search. Mutually exclusive with lat/lon coordinate search.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "example": "10117" }, { "name": "lat", "in": "query", "required": false, "description": "Latitude for reverse postcode search. Must be used together with lon and without postcode.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": false, "description": "Longitude for reverse postcode search. Must be used together with lat and without postcode.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "countrycode", "in": "query", "required": false, "description": "Optional ISO 3166-1 alpha-2 country code filter.", "schema": { "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" ] }, "example": "de" }, { "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" }, { "name": "format", "in": "query", "required": false, "description": "Response format.", "schema": { "type": "string", "enum": [ "json", "geojson", "xml" ], "default": "geojson" } }, { "name": "geometry", "in": "query", "required": false, "description": "Postcode geometry representation. Use point for centroid geometry or original for source geometry.", "schema": { "type": "string", "enum": [ "point", "original" ], "default": "point" } } ], "responses": { "200": { "description": "Postcode search result in the requested format.", "content": { "application/geo+json": { "schema": { "$ref": "#/components/schemas/PostcodeFeatureCollection" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PostcodeFeatureCollection" } }, "application/xml": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid Geoapify API key." }, "429": { "description": "Rate limit or quota exceeded." }, "500": { "description": "Internal gateway error." } } } }, "/postcode/list": { "get": { "tags": [ "Postcode" ], "operationId": "listPostcodes", "summary": "List postcodes", "description": "List postcode features matching optional text, spatial filters, country filters, and pagination parameters.", "parameters": [ { "name": "apiKey", "in": "query", "required": true, "description": "Geoapify API key.", "schema": { "type": "string" }, "example": "YOUR_API_KEY" }, { "name": "text", "in": "query", "required": false, "description": "Free-text postcode query.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "example": "101" }, { "name": "filter", "in": "query", "required": false, "description": "Optional spatial or place filter. Supported values include rect:lon1,lat1,lon2,lat2, circle:lon,lat,radius, and place:place_id. Multiple filters can be repeated or separated with |.", "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^(rect:-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?|circle:-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,\\d+(\\.\\d+)?|place:?[a-f0-9]{2,2048})$" } }, "examples": { "rectangle": { "summary": "Rectangle filter", "value": [ "rect:13.0884,52.3383,13.7611,52.6755" ] }, "circle": { "summary": "Circle filter", "value": [ "circle:13.405,52.52,5000" ] }, "place": { "summary": "Place filter", "value": [ "place:51f076656bb5d12a4059dc0a6139b98e4a40f00101f90123" ] } } }, { "name": "bias", "in": "query", "required": false, "description": "Optional result bias. Supported values include proximity:lon,lat, circle:lon,lat,radius, and rect:lon1,lat1,lon2,lat2. Multiple bias values can be repeated or separated with |.", "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^(proximity:-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?|rect:-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?|circle:-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,\\d+(\\.\\d+)?)$" } }, "examples": { "proximity": { "summary": "Proximity bias", "value": [ "proximity:13.405,52.52" ] }, "circle": { "summary": "Circle bias", "value": [ "circle:13.405,52.52,5000" ] } } }, { "name": "countrycode", "in": "query", "required": false, "description": "Optional ISO 3166-1 alpha-2 country code filter.", "schema": { "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" ] }, "example": "de" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of postcode results to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 5 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of matching results to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "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" }, { "name": "format", "in": "query", "required": false, "description": "Response format.", "schema": { "type": "string", "enum": [ "json", "geojson", "xml" ], "default": "geojson" } }, { "name": "geometry", "in": "query", "required": false, "description": "Postcode geometry representation. Use point for centroid geometry or original for source geometry.", "schema": { "type": "string", "enum": [ "point", "original" ], "default": "point" } } ], "responses": { "200": { "description": "Postcode list result in the requested format.", "content": { "application/geo+json": { "schema": { "$ref": "#/components/schemas/PostcodeFeatureCollection" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PostcodeFeatureCollection" } }, "application/xml": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid Geoapify API key." }, "429": { "description": "Rate limit or quota exceeded." }, "500": { "description": "Internal gateway error." } } } } }, "components": { "schemas": { "PostcodeFeatureCollection": { "type": "object", "additionalProperties": true, "required": [ "type", "features" ], "properties": { "type": { "const": "FeatureCollection" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/PostcodeFeature" } } } }, "PostcodeFeature": { "type": "object", "additionalProperties": true, "required": [ "type", "properties", "geometry" ], "properties": { "type": { "const": "Feature" }, "properties": { "$ref": "#/components/schemas/PostcodeProperties" }, "geometry": { "oneOf": [ { "$ref": "#/components/schemas/PointGeometry" }, { "$ref": "#/components/schemas/GeoJsonGeometry" } ] } } }, "PostcodeProperties": { "type": "object", "additionalProperties": true, "properties": { "postcode": { "type": "string", "description": "Postal or ZIP code." }, "country": { "type": "string", "description": "Country name." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "state": { "type": "string", "description": "State, region, province, or administrative area." }, "city": { "type": "string", "description": "City, town, village, or locality." }, "place_id": { "type": "string", "description": "Geoapify encoded place identifier." } } }, "PointGeometry": { "type": "object", "additionalProperties": false, "required": [ "type", "coordinates" ], "properties": { "type": { "const": "Point" }, "coordinates": { "type": "array", "minItems": 2, "maxItems": 2, "prefixItems": [ { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude." }, { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude." } ] } } }, "GeoJsonGeometry": { "type": "object", "additionalProperties": true, "required": [ "type", "coordinates" ], "properties": { "type": { "type": "string", "description": "GeoJSON geometry type." }, "coordinates": { "description": "GeoJSON coordinates.", "type": "array" } } } } } }