--- title: "Retrieve coordinates by postal code" method: POST path: "/postalcode" tags: ["Places_Geocoding"] --- # Retrieve coordinates by postal code `POST /postalcode` ## Query parameters - `key` string, 32 character alphanumeric string, required ## Request body - object - `postalcode` string — Provide the postal code for which the information is needed. At least one of (postalcode + country) or at needs to be provided. Please note that only 1 postal code can be requested. [See this example](#note). - `country` string — Country containing the postal code or the location. It is mandatory if postalcode is provided in the request. [See this example](#note). Please check the [API Query Limits](#api-query-limits) section below for a list of the countries covered by the Geocode Postcode API. Users can provide either the name or the alpha-2/3 code as per the [ISO 3166-1 standard](https://en.wikipedia.org/wiki/ISO_3166-1) of a country covered by the API as input for this parameter. - `at` object — Location coordinates that you want to get the postal code of. If not providing postalcode in the request, at becomes mandatory. Please note that only 1 point can be requested. [See this example](#note). - `lat` number — Latitude of the location. - `lng` number — Longitude of the location. - `format` 'geojson' — Specify the format in which the boundary details of the post code will be returned. When specified, the boundary details will be returned in the geojson format. When not specified, the boundary details are returned in general format. ## Response `200` - object - `warning` string[] — Returns a message, in case the input provided triggers any warnings. - `places` object — An object that contains details about the place that was provided in the input. - `geopoint` object — Refers to the geographic coordinate denoting the center of the postal code in latitude, longitude format. - `lat` number — Latitude of the location. - `lng` number — Longitude of the location. - `country` string — Name of the country containing the geographic coordinate point / postal code provided in the input request. - `countryCode` string — Returns the [alpha-3 ISO code](https://www.iban.com/country-codes) of the country containing the postalcode returned. - `state` string — Name of the state or province containing the geographic coordinate point / postal code provided in the input request. - `district` string — Name of the district or region containing the geographic coordinate point / postal code provided in the input request. - `subdistrict` string — Name of the sub-district or sub-region containing the postal code or geographic coordinate point / postal code provided in the input request - `postalcode` string — Returns the postal code associated with the requested geographic coordinate point or the postal code itself as provided in the input API request. - `address` string — Returns the address of the postalcode returned. - `distance` number — This property is returned only when the API is requested to fetch the postal code containing the location coordinate provided in the at input parameter. distance denotes the straight line distance, in meters, from the requested location coordinate to the postal code centroid. - `boundary` object — An object containing the boundary details of the postal code area. This object will not be returned in case the boundary information of the postal code provided is not available (only for selected countries). Please note the contents of this object will change based on the format field in the input. When the format field is not present in the input this object would contain multipolygon - polygon - points objects depending on the boundary of the given postal code. When the format field is present in the input, then the contents of this object would match the [geojson format and standard](https://datatracker.ietf.org/doc/html/rfc7946). - `multipolygon` object[] — An array of objects containing information about all the polygons forming the postal code area. In case, the postal code area is formed by multiple polygons not containing each other, a matching count of polygon objects will be returned. Please note that this object is returned only when format field is not specified in the input, otherwise it is not present in the response. - `polygon` object[] — An object containing the details of a single polygon that is a part of the postal code area. In case the postal code area contains other polygon(s), the details of such polygon(s) would be returned through an array of points object. - `points` object[] — Represents an array of geographic coordinates that define a polygon boundary. - `lat` number — Latitude of the coordinate. - `lng` number — Longitude of the coordinate. - `type` string — Type of the geoJSON object. This parameter is returned when the format field is set to geojson in the input request, otherwise it is not present in the response. The contents of this object follow the [geoJSON standard](https://datatracker.ietf.org/doc/html/rfc7946). - `geometry` object — An object with geoJSON details of the boundary. This object is returned when the format field is set to geojson in the input request, otherwise it is not present in the response. The contents of this object follow the [geoJSON standard](https://datatracker.ietf.org/doc/html/rfc7946). - `type` string — Type of the geoJSON geometry. - `coordinates` array[] — An array of coordinates in the [longitude, latitude] format, representing the coordinates points which lie on the boundary of the postal code area. - array[] - number[] - `properties` string — Property associated with the geoJSON shape. --- [API](https://skmtc.net/nextbillion-ai/apis/one-spec-service.md) · [All operations](https://skmtc.net/nextbillion-ai/apis/one-spec-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nextbillion-ai/one-spec-service/versions/b647f1808dda/schema)