Skip to content

Geocode - address

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

Endpoint URL

(POST | GET) https://valid.geposit.se/1.7/geocode/address/{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
response_format Sets the format for the API response.
The following values are supported:
- xml
- json(Default value)
street Required
Either the full street address including street name / street number / attribution or or just the street name together street number/attribution provided as separate arguments (street_number/extra_number/letter)

Example:
street=Litselby gård
(full address)
street=Storgatan 12
(full address)
street=Storgatan&street_number=12
(street parameter contains street name, street number provided separately)
street=Storgatan 12B
(full address)
street=Storgatan&street_number=12&letter=B
(street parameter contains street name, street number and letter provided separately)
street=Gullyckeskärsvägen 203-28
(street address with both primary and secondary street number - full address provided in street parameter)
street=Gullyckeskärsvägen&street_number=203&extra_number=28
(street parameter contains street name, street number and extra number provided separately)
street_number The street number of the address, unless it is given as a part of the street parameter.

Example:
street=Storgatan&street_number=12
letter The letter of the address, unless it is given as a part of the street parameter.

Example:
street=Storgatan&street_number=12&letter=A
extra_number The additional/secondary street number of the address, unless it is given as a part of the street parameter.

Example:
street=Landsvägen&street_number=22&extra_number=120
postalcode Required
The postalcode of the address.
Example: postalcode=12345
locality Required
The locality of the address.
Example: locality=Stockholm
suggestions Decides if the API should return suggestions for correct addresses if an incorrect address is geocoded. The following values are supported:
- 0 (No suggestions)
- 1 (Suggestions) (Default value)
lang Control the language used in response output (status, errors etc.) :
- se - Swedish (Default)
- no - Norweigan
- dk - Danish
- fi - Finish
- en - English
add Comma separated string with administrative division relations you want to be added to each address suggestion/match in the response.

Example:
add=adm1,adm3,adm5

List of supported administrative divisions in each country

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 address
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 address input - declared as a query object (referenced below)
response » interpretation Object Object containing the parsed version of the incoming address - declared as a interpretation object (referenced below)
response » is_valid Integer States if the sent in address is valid or not. Possible values are:
- 0 (Not valid)
- 1 (Valid)
response » status Integer Status code that gives detailed information about the geocode result. This code details both general errors and detailed geocode errors.
response » status_text String The time it took to process the request
response » errors Object Error(s) detected in the address - declared as an error object (referenced below)
response » match Object If the address is correct - this object will hold a detailed description of the matched address - declared as an match object (referenced below)
response » suggestions Array If the address is invalid - this array will hold zero or more suggestion(s) - each suggestion being declared as a suggestion object (referenced below)

Query object

Key Value type Value description
street String Street name or full street address
street_number String Street number
letter String Letter used in street number attribution, e.g. Storgatan 12A
extra_number String Additional/extra street number *
* Some addresses have dual street number attributing, e.g. Landsbyvägen 2-220.

You can choose from providing the full street address in the street parameter, like this:
street=Landsbyvägen 2-220
..or divided like this:
street=Landsbyvägen&street_number=2&extra_number=220
postalcode String Postal code of the address
locality String Locality / city of the address

Interpretation object

Key Value type Value description
street String Parsed street name
street_number String Parsed street number
letter String Parsed letter (used in street number attribution, e.g. Storgatan 12A)
extra_number String Parsed additional/extra street number *
* Some addresses have dual street number attributing, e.g. Landsbyvägen 2-220.

extra_number will be 220 in this example.
extra String Additional/extra information in the street address *
* Some addresses have additional information attached to it that's not part of the actual street address, like floor level or apartment number:
street=Storgatan 12, LGH 1204.
In this example , LGH 1204 will be put in the extra attribute.
postalcode String Parsed postal code
locality String Parsed locality / city

Suggestion object

Key Value type Value description
address_type String Address type
List of possible address types
street String Street name
street_number String Street number
letter String Letter (used in street number attribution, e.g. Storgatan 12A)
extra_number String Additional/extra street number *
* Some addresses have dual street number attributing, e.g. Landsbyvägen 2-220.

extra_number will be 220 in this example.
extra String Additional/extra information in the incoming street address that was not part of the actual street address, like floor level or apartment number
postalcode String Postal code
locality String Locality / city
errors Object Error(s) / Difference(s) compared to the address provided in the request - declared as an error object (referenced below)
geocode_accuracy Integer Tells you how exact/accurate the position is. The following values are supported:
- 1 Exact position
- 2 Approximate position

Match object

Key Value type Value description
address_type String Address type
List of possible address types
street String Street name
street_number String Street number
letter String Letter (used in street number attribution, e.g. Storgatan 12A)
extra_number String Additional/extra street number *
* Some addresses have dual street number attributing, e.g. Landsbyvägen 2-220.

extra_number will be 220 in this example.
extra String Additional/extra information in the incoming street address that was not part of the actual street address, like floor level or apartment number
postalcode String Postal code
locality String Locality / city
x_lon Float X / Longitude (WGS84 - EPSG:4326)
y_lat Float Y / Latitude (WGS84 - EPSG:4326)
geocode_accuracy Integer Tells you how exact/accurate the position is. The following values are supported:
- 1 Exact position
- 2 Approximate position

Error object

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

Examples

Example - Geocode of a correct Swedish address

Address to geocode

street postalcode locality
Drottninggatan 45 11121 Stockholm

Request

curl https://valid.geposit.se/1.7/geocode/address/se -d "street=Drottninggatan 45&postalcode=11121&locality=Stockholm&response_format=json&api_key={API_KEY}"

Response

{
  "name": "Valid API Norden",
  "type": "Geocode address",
  "version": "latest",
  "charset": "utf-8",
  "response": {
    "response_time": 0.227,
    "query": {
      "street": "Drottninggatan 45",
      "postalcode": "11121",
      "locality": "Stockholm"
    },
    "interpretation": {
      "postalcode": "11121",
      "locality": "Stockholm",
      "street": "Drottninggatan",
      "street_number": "45"
    },
    "is_valid": 1,
    "status": 11,
    "status_text": "Adressen är korrekt",
    "match": {
      "address_type": "NB",
      "street": "Drottninggatan",
      "street_number": "45",
      "extra_number": "",
      "letter": "",
      "postalcode": "11121",
      "locality": "Stockholm",
      "x_lon": 18.0622452563544,
      "y_lat": 59.3324538219202,
      "geocode_accuracy": 1
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<api>
 <name>Valid API Norden</name>
 <type>Geocode address</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <response>
  <response_time>0,353</response_time>
  <query>
   <street>Drottninggatan 45</street>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
  </query>
  <interpretation>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
   <street>Drottninggatan</street>
   <street_number>45</street_number>
  </interpretation>
  <is_valid>1</is_valid>
  <status>11</status>
  <status_text>Adressen är korrekt</status_text>
  <match>
   <address_type>NB</address_type>
   <street>Drottninggatan</street>
   <street_number>45</street_number>
   <extra_number></extra_number>
   <letter></letter>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
   <x_lon>18,062245256354</x_lon>
   <y_lat>59,33245382192</y_lat>
   <geocode_accuracy>1</geocode_accuracy>
  </match>
 </response>
</api>

Example - Geocode of a correct Swedish address (same as above) with street number provided as separate argument

Address to geocode

street street_number postalcode locality
Drottninggatan 45 11121 Stockholm

Request

curl https://valid.geposit.se/1.7/geocode/address/se -d "street=Drottninggatan&street_number=45&postalcode=11121&locality=Stockholm&response_format=json&api_key={API_KEY}"

Response

{
  "name": "Valid API Norden",
  "type": "Geocode address",
  "version": "latest",
  "charset": "utf-8",
  "response": {
    "response_time": 0.215,
    "query": {
      "street": "Drottninggatan",
      "street_number": "45",
      "postalcode": "11121",
      "locality": "Stockholm"
    },
    "interpretation": {
      "postalcode": "11121",
      "locality": "Stockholm",
      "street": "Drottninggatan",
      "street_number": "45"
    },
    "is_valid": 1,
    "status": 11,
    "status_text": "Adressen är korrekt",
    "match": {
      "address_type": "NB",
      "street": "Drottninggatan",
      "street_number": "45",
      "extra_number": "",
      "letter": "",
      "postalcode": "11121",
      "locality": "Stockholm",
      "x_lon": 18.0622452563544,
      "y_lat": 59.3324538219202,
      "geocode_accuracy": 1
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<api>
 <name>Valid API Norden</name>
 <type>Geocode address</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <response>
  <response_time>0,339</response_time>
  <query>
   <street>Drottninggatan</street>
   <street_number>45</street_number>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
  </query>
  <interpretation>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
   <street>Drottninggatan</street>
   <street_number>45</street_number>
  </interpretation>
  <is_valid>1</is_valid>
  <status>11</status>
  <status_text>Adressen är korrekt</status_text>
  <match>
   <address_type>NB</address_type>
   <street>Drottninggatan</street>
   <street_number>45</street_number>
   <extra_number></extra_number>
   <letter></letter>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
   <x_lon>18,062245256354</x_lon>
   <y_lat>59,33245382192</y_lat>
   <geocode_accuracy>1</geocode_accuracy>
  </match>
 </response>
</api>

Example - Using add parameter to add administrative relations to the address

Address to geocode

street postalcode locality
Drottninggatan 45 11121 Stockholm

Request

curl https://valid.geposit.se/1.7/geocode/address/se -d "street=Drottninggatan 45&postalcode=11121&locality=Stockholm&add=adm1,adm3,adm5&response_format=json&api_key={API_KEY}"

Response

{
  "name": "Valid API Norden",
  "type": "Geocode address",
  "version": "latest",
  "charset": "utf-8",
  "response": {
    "response_time": 0.257,
    "query": {
      "street": "Drottninggatan 45",
      "postalcode": "11121",
      "locality": "Stockholm"
    },
    "interpretation": {
      "postalcode": "11121",
      "locality": "Stockholm",
      "street": "Drottninggatan",
      "street_number": "45"
    },
    "is_valid": 1,
    "status": 11,
    "status_text": "Adressen är korrekt",
    "match": {
      "address_type": "NB",
      "street": "Drottninggatan",
      "street_number": "45",
      "extra_number": "",
      "letter": "",
      "postalcode": "11121",
      "locality": "Stockholm",
      "adm1": "Stockholm",
      "adm1_code": "01",
      "adm3": "Stockholms domkyrkoförs.",
      "adm3_code": "018001",
      "adm5": "Stockholms domkyrkoförs.",
      "adm5_code": "018001",
      "x_lon": 18.0622452563544,
      "y_lat": 59.3324538219202,
      "geocode_accuracy": 1
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<api>
 <name>Valid API Norden</name>
 <type>Geocode address</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <response>
  <response_time>0,332</response_time>
  <query>
   <street>Drottninggatan 45</street>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
  </query>
  <interpretation>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
   <street>Drottninggatan</street>
   <street_number>45</street_number>
  </interpretation>
  <is_valid>1</is_valid>
  <status>11</status>
  <status_text>Adressen är korrekt</status_text>
  <match>
   <address_type>NB</address_type>
   <street>Drottninggatan</street>
   <street_number>45</street_number>
   <extra_number></extra_number>
   <letter></letter>
   <postalcode>11121</postalcode>
   <locality>Stockholm</locality>
   <adm1>Stockholm</adm1>
   <adm1_code>01</adm1_code>
   <adm3>Stockholms domkyrkoförs.</adm3>
   <adm3_code>018001</adm3_code>
   <adm5>Stockholms domkyrkoförs.</adm5>
   <adm5_code>018001</adm5_code>
   <x_lon>18,062245256354</x_lon>
   <y_lat>59,33245382192</y_lat>
   <geocode_accuracy>1</geocode_accuracy>
  </match>
 </response>
</api>