Validate Postcode

Endpoint for checking if an postcode in a specific country is valid or not.

Endpoint URL

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

where {COUNTRY_CODE} is replaced with one of the following supported country codes:

  • se (Sweden)
  • no (Norway)
  • dk (Denmark)
  • fi (Finland)

Supported parameters

Query parameter

Value

api_key

Required
A valid API key

postcode

Required
The postcode to validate.
Example: postcode=12345

response_format

Sets the format for the API response.
The following values are supported:
_ xml

  • json(Default value)

administrative

Includes the administrative division relations for the postcode in the response.

  • true
  • false (Default value)

See Glossary for list of supported administrative divisions in each country

coordinate(Require extra permission)

Includes the coordinate for the postcode (centroid) in the response.

  • true
  • false (Default value)

Response

Key

Value type

Value description

name

String

The name of the API

version

String

The API version

response

Object

The main response object holding all data regarding the validated postcode

response_time

Float

The time it took for the service to process this request

query

Object

Object containing the request parameters detected/used for postcode input - declared as a query object (referenced below)

interpretation

Object

Object containing the parsed version of the incoming postcode - declared as a interpretation object (referenced below)

is_valid

Integer

States if the sent in postal code is valid or not. Possible values are:

  • false (Not valid)
  • true (Valid)

match

Array

If the postcode is correct - this array will contain an object with detailed description of the matched postcode - declared as an match object (referenced below)

Query object

KeyValue typeValue description
postcodeStringThe postal code sent for validation formatted as in the request input parameter

Interpretation object

KeyValue typeValue description
postcodeStringParsed postal code

Match object

KeyValue typeValue description
postcodeStringPostal code
localityStringLocality / city

Error object

A key/value based object holding all the errors that were found with the incoming postal code. Each key represent an error code and the value for that key gives you a textual representation of that error.

Possible error codes

CodeExplanation
300Postalcode is missing
301Unknown format for the postal code
302Incorrect postcode

Examples

Example - Validation of a correct Swedish postcode

Request

curl https://app-api.geposit.se/v2.0/validate/postcode/se -d "postcode=11121&response_format=json&api_key={API_KEY}"

Response

{
  "version": "2.0",
  "response": {
    "response_time": 0.159,
    "query": {
      "postcode": "11121"
    },
    "interpretation": {
      "postcode": "11121"
    },
    "is_valid": 1,
    "match": {
      "postcode": "11121",
      "locality": "Stockholm"
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
 <version>2.0</version>
 <response_time>0,182</response_time>
 <query>
  <postcode>19999</postcode>
 </query>
 <interpretation>
  <postcode>19999</postcode>
 </interpretation>
 <is_valid>false</is_valid>
 <errors>
  <error>
   <error_code>302</error_code>
   <error_text>Felaktigt postnummer</error_text>
  </error>
 </errors>
</api>

Example - Validation of an invalid Swedish postcode

Request

curl https://app-api.geposit.se/v2.0/validate/postcode/se -d "postcode=19999&response_format=json&api_key={API_KEY}"

Response

{
  "version": "2.0",
  "charset": "utf-8",
  "response": {
    "response_time": 0.092,
    "query": {
      "postcode": "19999"
    },
    "interpretation": {
      "postcode": "19999"
    },
    "is_valid": 0,
    "errors": {
      "302": "Felaktigt postnummer"
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
 <version>2.0</version>
 <response_time>0.182</response_time>
 <query>
  <postcode>19999</postcode>
 </query>
 <interpretation>
  <postcode>19999</postcode>
 </interpretation>
 <is_valid>false</is_valid>
 <errors>
  <error>
   <error_code>302</error_code>
   <error_text>Felaktigt postnummer</error_text>
  </error>
 </errors>
</api>