Validate Postcode

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

Key	Value type	Value description
postcode	String	The postal code sent for validation formatted as in the request input parameter

Interpretation object

Key	Value type	Value description
postcode	String	Parsed postal code

Match object

Key	Value type	Value description
postcode	String	Postal code
locality	String	Locality / 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

Code	Explanation
300	Postalcode is missing
301	Unknown format for the postal code
302	Incorrect 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>