Validate Postcode

Endpoint URL

GET https://app-api.geposit.se/v2.0/validate/postcode/{COUNTRY_CODE}

{COUNTRY_CODE} is se, no, dk, fi or ax. Authentication, response status and permissions are described in Valid Intro. Full reference: Validate Postcode.

To check many postcodes in one request, use Validate Multi Postcode.

Parameters

Query parameter	Description
`postcode`	Required. The postcode, digits only. Example: `postcode=11121`
`response_format`	`json` (default) or `xml`.
`administrative`	`true` adds administrative divisions. Needs a permission. The codes are those of one address in the postcode; a postcode that crosses a boundary still gets one set.
`coordinate`	`true` adds the postcode's centre point as `latitude` and `longitude`. Needs a permission.

Send Swedish postcodes without the space (11121, not 111 21).

Response

Key	Type	Description
`version`	String	API version
`response_time`	Float	Processing time in seconds
`query`	Object	`postcode` as received
`interpretation`	Object	`postcode` as parsed
`is_valid`	Boolean	`true` when the postcode exists
`status`	Integer	`302` valid, `300` suggestions, `404` nothing found, `400` bad request. See Response status
`match`	Array	When the postcode is valid: one object with `postcode`, `locality` and `address_type`
`suggestions`	Array	When the postcode is not valid: postcodes that start with the input, each with `errors` (for example `[302]`, needs the error-codes permission)

With administrative=true and coordinate=true the objects also carry adm1_code … adm5_name, latitude and longitude.

Error codes for postcodes: 300 Postal code is missing, 301 Unknown format for the postal code, 302 Postal code is incorrect, 304, 306, 307, 308. See Glossary.

Examples

A valid postcode

curl -G https://app-api.geposit.se/v2.0/validate/postcode/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "postcode=11121"

{
  "version": "2.0",
  "response_time": 0.0031,
  "query": {
    "postcode": "11121"
  },
  "interpretation": {
    "postcode": "11121"
  },
  "is_valid": true,
  "status": 302,
  "match": [
    {
      "address_type": "NB",
      "postcode": "11121",
      "locality": "Stockholm"
    }
  ]
}

<Validate>
  <version>2.0</version>
  <response_time>0.0031</response_time>
  <query>
    <postcode>11121</postcode>
  </query>
  <interpretation>
    <postcode>11121</postcode>
  </interpretation>
  <is_valid>true</is_valid>
  <status>302</status>
  <match>
    <address_type>NB</address_type>
    <postcode>11121</postcode>
    <locality>Stockholm</locality>
  </match>
</Validate>

An incomplete postcode

A prefix returns every postcode that starts with it, as suggestions:

curl -G https://app-api.geposit.se/v2.0/validate/postcode/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "postcode=1112"

{
  "version": "2.0",
  "response_time": 0.0040,
  "query": {
    "postcode": "1112"
  },
  "interpretation": {
    "postcode": "1112"
  },
  "is_valid": false,
  "status": 300,
  "suggestions": [
    { "address_type": "NB", "postcode": "11120", "locality": "Stockholm", "errors": [302] },
    { "address_type": "NB", "postcode": "11121", "locality": "Stockholm", "errors": [302] },
    { "address_type": "NB", "postcode": "11122", "locality": "Stockholm", "errors": [302] }
  ]
}

(Shortened: the real response lists all matching postcodes.)