Geocode - postalcode¶

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

Endpoint URL¶

(POST | GET) https://valid.geposit.se/1.6/geocode/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 geocode. 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 "Geocode"
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 geocoded 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
x_lon	Float	X / Longitude (WGS84 - EPSG:4326)
y_lat	Float	Y / Latitude (WGS84 - EPSG:4326)

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.6/geocode/postalcode/se -d "postalcode=11121&response_format=json&api_key={API_KEY}"

Response¶

JSON Response (response_format=json)

{
  "name": "Valid API Norden",
  "type": "Geocode postalcode",
  "version": "latest",
  "charset": "utf-8",
  "response": {
    "response_time": 0.307,
    "query": {
      "postalcode": "11121"
    },
    "interpretation": {
      "postalcode": "11121"
    },
    "is_valid": 1,
    "match": {
      "postalcode": "11121",
      "locality": "Stockholm",
      "x_lon": 18.0605585438891,
      "y_lat": 59.3323178094881
    }
  }
}

XML Response (response_format=xml)

<?xml version="1.0" encoding="UTF-8"?>
<api>
 <name>Valid API Norden</name>
 <type>Geocode postalcode</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <response>
  <response_time>0,165</response_time>
  <query>
   <postalcode>11121</postalcode>
  </query>
  <interpretation>
   <postalcode>11121</postalcode>
  </interpretation>
  <is_valid>1</is_valid>
  <match>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
   <x_lon>18,060558543889</x_lon>
   <y_lat>59,332317809488</y_lat>
  </match>
 </response>
</api>

Example - Validation of an invalid Swedish postalcode¶

Request¶

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

Response¶

JSON Response (response_format=json)

{
  "name": "Valid API Norden",
  "type": "Geocode postalcode",
  "version": "latest",
  "charset": "utf-8",
  "response": {
    "response_time": 0.267,
    "query": {
      "postalcode": "19999"
    },
    "interpretation": {
      "postalcode": "19999"
    },
    "is_valid": 0,
    "errors": {
      "302": "Felaktigt postnummer"
    }
  }
}

XML Response (response_format=xml)

<?xml version="1.0" encoding="UTF-8"?>
<api>
 <name>Valid API Norden</name>
 <type>Geocode postalcode</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <response>
  <response_time>0,166</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>