Validate Address

Endpoint URL

(GET) https://app-api.geposit.se/v2.0/validate/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 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
postcode	Required The postcode of the address. Example: postcode=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 validated. The following values are supported: _ true (Default value) _ false
administrative	Includes the administrative division relations for the address 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 address in the response. _ true _ false (Default value)
property_designation (Require extra permission)	Includes property designation for Swedish addresses (Fastighetsbeteckning). _ true _ false (Default value)
uuid (Require extra permission)	Includes the UUID (unique key) for the address in the response. _ true _ false (Default value)
deso_ (Require extra permission)	Includes the DeSo code for the address in the response. _ true _ false (Default value)
neighborhood (Require extra permission)	Includes the neighborhoods for the address in the response. _ true _ false (Default value)

Note
To be able to request uuid attribute, you need to have a specific permission.

Response

Key	Value Type	Value description
version	String	The API version
response_time	Float	The time it took for the service to process this request
query	Object	Object containing the request parameters detected/used for address input - declared as a query object (referenced below)
interpretation	Object	Object containing the parsed version of the incoming address - declared as a interpretation object (referenced below)
is_valid	Integer	States if the sent in address is valid or not. Possible values are: _ false (Not valid) _ true (Valid)
status	Integer	Status code that gives detailed information about the validation result. This code details both general errors and detailed validation errors.
match	Array	If the address is correct - this array will contain an object with detailed description of the matched address - declared as an match object (referenced below)
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)
errors	Object	Error(s) detected in the query - declared as an error 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
postcode	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.
postcode	String	Parsed postal code
locality	String	Parsed locality / city

Suggestion object

Key	Value type	Value description
address_type	String	Address type See Glossary for 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
postcode	String	Postal code
locality	String	Locality / city
errors	Array	List of errors codes for the result
uuid	String	Unique identifier of the address. (Only available to Sweden)
latitude	Float	Latitude of the address if existing
longitude	Float	Longitude of the address if existing
roperty_desgination	String	Includes property designation for Swedish addresses (Fastighetsbeteckning).
admock:p_code	String	Administrative code for levels 1-5 See Glossary for list of supported administrative divisions in each country
admock:p_name	String	Administrative name for levels 1-5 See Glossary for list of supported administrative divisions in each country
localisations	Array	Array of localisation objects

Match object

Key	Value type	Value description
address_type	String	Address type See Glossary for 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
postcode	String	Postal code
locality	String	Locality / city
latitude	Float	Latitude of the address if existing
longitude	Float	Longitude of the address if existing
property_desgination	String	Includes property designation for Swedish addresses (Fastighetsbeteckning).
admock:p_code	String	Administrative code for levels 1-5 See Glossary for list of supported administrative divisions in each country
admock:p_name	String	Administrative name for levels 1-5 See Glossary for list of supported administrative divisions in each country
localisations	Array	Array of localisation objects
errors	Array	List of errors codes for the result

Note
Sometimes, you might see an additional parameters like street_alt and locality_alt in the response for validation requests against Finland (country code: fi). These attributes represent the alternative street name and alternative locality names which comes in Swedish language.

Also it is possible to use Swedish address names on validation requests against Finland (country code: fi).

Localisation object

Key	Value type	Value description
locale	String	Locale for this translation
street	String	Translation for street
locality	String	Translation for locality

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. See Glossary for list of possible error codes and explanation

Examples

Example - Validation of a correct Swedish address

Address to validate

street	postcode	locality
Drottninggatan 45	11121	Stockholm

Request

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

Response

{
    "version": "2.0",
    "response_time": 0.029,
    "query": {
        "street": "Drottninggatan 45",
        "locality": "Stockholm",
        "postcode": "11121"
    },
    "interpretation": {
        "postcode": "11121",
        "locality": "Stockholm",
        "street": "Drottninggatan",
        "street_number": "45"
    },
    "is_valid": true,
    "status": 11,
    "match": {
        "street": "Drottninggatan",
        "street_number": "45",
        "extra_number": "",
        "letter": "",
        "postcode": "11121",
        "locality": "Stockholm",
        "address_type": "NB"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <version>2.0</version>
    <response_time>0,022</response_time>
    <query>
      <street>Drottninggatan 45</street>
      <locality>Stockholm</locality>
      <postcode>11121</postcode>
    </query>
    <interpretation>
      <postcode>11121</postcode>
      <locality>Stockholm</locality>
      <street>Drottninggatan</street>
      <street_number>45</street_number>
    </interpretation>
    <is_valid>true</is_valid>
    <status>11</status>
    <match>
      <street>Drottninggatan</street>
      <street_number>45</street_number>
      <extra_number></extra_number>
      <letter></letter>
      <postcode>11121</postcode>
      <locality>Stockholm</locality>
      <address_type>NB</address_type>
    </match>
</api>

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

Address to validate

street	street_number	postcode	Stockholm
Drottninggatan	45	11121	Stockholm

Request

curl https://app-api.geposit.se/v2.0/validate/address/se -d "street=Drottninggatan&street_number=45&postcode=11121&locality=Stockholm&response_format=json&api_key={API_KEY}"

Response

{
    "version": "2.0",
    "response_time": 0.029,
    "query": {
        "street": "Drottninggatan",
        "street_number": "45",
        "locality": "Stockholm",
        "postcode": "11121"
    },
    "interpretation": {
        "postcode": "11121",
        "locality": "Stockholm",
        "street": "Drottninggatan",
        "street_number": "45"
    },
    "is_valid": true,
    "status": 11,
    "match": {
        "street": "Drottninggatan",
        "street_number": "45",
        "extra_number": "",
        "letter": "",
        "postcode": "11121",
        "locality": "Stockholm",
        "address_type": "NB"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <version>2.0</version>
    <response_time>0,022</response_time>
    <query>
        <street>Drottninggatan</street>
        <street_number>45</street_number>
        <locality>Stockholm</locality>
        <postalcode>11121</postalcode>
    </query>
    <interpretation>
        <postalcode>11121</postalcode>
        <locality>Stockholm</locality>
        <street>Drottninggatan</street>
        <street_number>45</street_number>
    </interpretation>
    <is_valid>true</is_valid>
    <status>11</status>
    <match>
        <street>Drottninggatan</street>
        <street_number>45</street_number>
        <extra_number></extra_number>
        <letter></letter>
        <postalcode>11121</postalcode>
        <locality>Stockholm</locality>
        <address_type>NB</address_type>
    </match>
</api>

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

Address to validate

street	postcode	locality
Drottninggatan 45	11121	Stockholm

Request

curl https://app-api.geposit.se/v2.0/validate/address/se -d "street=Drottninggatan 45&postcode=11121&locality=Stockholm&administrative=true&response_format=json&api_key={API_KEY}"

Response

{
    "version": "2.0",
    "response_time": 0.026,
    "query": {
        "street": "Drottninggatan 45",
        "locality": "Stockholm",
        "postcode": "11121"
    },
    "interpretation": {
        "postcode": "11121",
        "locality": "Stockholm",
        "street": "Drottninggatan",
        "street_number": "45"
    },
    "is_valid": true,
    "status": 11,
    "match": {
        "street": "Drottninggatan",
        "street_number": "45",
        "extra_number": "",
        "letter": "",
        "postcode": "11121",
        "locality": "Stockholm",
        "address_type": "NB",
        "adm1_code": "01",
        "adm1_name": "Stockholm",
        "adm3_code": "018001",
        "adm3_name": "Stockholms domkyrkoförs.",
        "adm5_code": "018001",
        "adm5_name": "Stockholms domkyrkoförs."
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <version>2.0</version>
    <response_time>0,023</response_time>
    <query>
        <street>Drottninggatan 45</street>
        <locality>Stockholm</locality>
        <postcode>11121</postcode>
    </query>
    <interpretation>
        <postcode>11121</postcode>
        <locality>Stockholm</locality>
        <street>Drottninggatan</street>
        <street_number>45</street_number>
    </interpretation>
    <is_valid>true</is_valid>
    <status>11</status>
    <match>
        <street>Drottninggatan</street>
        <street_number>45</street_number>
        <extra_number></extra_number>
        <letter></letter>
        <postcode>11121</postcode>
        <locality>Stockholm</locality>
        <address_type>NB</address_type>
        <adm1_code>01</adm1_code>
        <adm1_name>Stockholm</adm1_name>
        <adm3_code>018001</adm3_code>
        <adm3_name>Stockholms domkyrkoförs.</adm3_name>
        <adm5_code>018001</adm5_code>
        <adm5_name>Stockholms domkyrkoförs.</adm5_name>
    </match>
</api>