Skip to content

Validate - postalcode


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

Endpoint URL

(POST | GET) https://valid.geposit.se/1.7/validate/postalcode/{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
postalcode Required
The postalcode to validate.
Example: postalcode=12345
response_format Sets the format for the API response.
The following values are supported:
- xml
- json(Default value)
lang Control the language used in response output (status, errors etc.) :
- se - Swedish (Default)
- no - Norweigan
- dk - Danish
- fi - Finish
- en - English

Response

Key Value type Value description
name String The name of the API
type String The type of service used, in this case "Validate"
version String The API version
charset String The character encoding of the response, always utf-8
response Object The main response object holding all data regarding the validated postalcode
response » response_time Float The time it took for the service to process this request
response » query Object Object containing the request parameters detected/used for postalcode input - declared as a query object (referenced below)
response » interpretation Object Object containing the parsed version of the incoming postalcode - declared as a interpretation object (referenced below)
response » is_valid Integer States if the sent in postalcode is valid or not. Possible values are:
- 0 (Not valid)
- 1 (Valid)
response » errors Object Error(s) detected in the postalcode - declared as an error object (referenced below)
response » match Object If the postalcode is correct - this object will hold a detailed description of the matched postalcode - declared as an match object (referenced below)

Query object

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

Interpretation object

Key Value type Value description
postalcode String Parsed postal code

Match object

Key Value type Value description
postalcode 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 postalcode

Examples


Example - Validation of a correct Swedish postalcode

Request

curl https://valid.geposit.se/1.7/validate/postalcode/se -d "postalcode=11121&response_format=json&api_key={API_KEY}"

Response

{
  "name": "Valid API Norden",
  "type": "Validate postalcode",
  "version": "latest",
  "charset": "utf-8",
  "response": {
    "response_time": 0.159,
    "query": {
      "postalcode": "11121"
    },
    "interpretation": {
      "postalcode": "11121"
    },
    "is_valid": 1,
    "match": {
      "postalcode": "11121",
      "locality": "Stockholm"
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
 <name>Valid API Norden</name>
 <type>Validate postalcode</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <response>
  <response_time>0,203</response_time>
  <query>
   <postalcode>11121</postalcode>
  </query>
  <interpretation>
   <postalcode>11121</postalcode>
  </interpretation>
  <is_valid>1</is_valid>
  <match>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
  </match>
 </response>
</api>

Example - Validation of an invalid Swedish postalcode

Request

curl https://valid.geposit.se/1.7/validate/postalcode/se -d "postalcode=19999&response_format=json&api_key={API_KEY}"

Response

{
  "name": "Valid API Norden",
  "type": "Validate postalcode",
  "version": "latest",
  "charset": "utf-8",
  "response": {
    "response_time": 0.092,
    "query": {
      "postalcode": "19999"
    },
    "interpretation": {
      "postalcode": "19999"
    },
    "is_valid": 0,
    "errors": {
      "302": "Felaktigt postnummer"
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
 <name>Valid API Norden</name>
 <type>Validate postalcode</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <response>
  <response_time>0,182</response_time>
  <query>
   <postalcode>19999</postalcode>
  </query>
  <interpretation>
   <postalcode>19999</postalcode>
  </interpretation>
  <is_valid>0</is_valid>
  <errors>
   <error>
    <error_code>302</error_code>
    <error_text>Felaktigt postnummer</error_text>
   </error>
  </errors>
 </response>
</api>