Validate - 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/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 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 validated. 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
uuid	Includes the UUID for the address in the response. This parameter only supports for requests related to the country Sweden. - `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
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 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 validation result. This code details both general errors and detailed validation 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)

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
uuid	String	Unique identifier of the address. (Only available to Sweden)

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).

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 - Validation of a correct Swedish address¶

Address to validate¶

street	postalcode	locality
Drottninggatan 45	11121	Stockholm

Request¶

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

Response¶

JSON Response (response_format=json)

{
    "name": "Valid API Norden",
    "type": "Address validation",
    "version": "1.7",
    "charset": "utf-8",
    "response": {
        "response_time": 0.029,
        "query": {
            "street": "Drottninggatan 45",
            "locality": "Stockholm",
            "postalcode": "11121"
        },
        "interpretation": {
            "postalcode": "11121",
            "locality": "Stockholm",
            "street": "Drottninggatan",
            "street_number": "45"
        },
        "is_valid": 1,
        "status": 11,
        "status_text": "Adressen är korrekt",
        "match": {
            "street": "Drottninggatan",
            "street_number": "45",
            "extra_number": "",
            "letter": "",
            "postalcode": "11121",
            "locality": "Stockholm",
            "address_type": "NB"
        }
    }
}

XML Response (response_format=xml)

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <name>Valid API Norden</name>
    <type>Address validation</type>
    <version>1.4</version>
    <charset>utf-8</charset>
    <response>
        <response_time>0,022</response_time>
        <query>
            <street>Drottninggatan 45</street>
            <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>1</is_valid>
        <status>11</status>
        <status_text>Adressen är korrekt</status_text>
        <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>
    </response>
</api>

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

Address to validate¶

street	street_number	postalcode	locality
Drottninggatan	45	11121	Stockholm

Request¶

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

Response¶

JSON Response (response_format=json)

{
    "name": "Valid API Norden",
    "type": "Address validation",
    "version": "1.7",
    "charset": "utf-8",
    "response": {
        "response_time": 0.029,
        "query": {
            "street": "Drottninggatan",
            "street_number": "45",
            "locality": "Stockholm",
            "postalcode": "11121"
        },
        "interpretation": {
            "postalcode": "11121",
            "locality": "Stockholm",
            "street": "Drottninggatan",
            "street_number": "45"
        },
        "is_valid": 1,
        "status": 11,
        "status_text": "Adressen är korrekt",
        "match": {
            "street": "Drottninggatan",
            "street_number": "45",
            "extra_number": "",
            "letter": "",
            "postalcode": "11121",
            "locality": "Stockholm",
            "address_type": "NB"
        }
    }
}

XML Response (response_format=xml)

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <name>Valid API Norden</name>
    <type>Address validation</type>
    <version>1.4</version>
    <charset>utf-8</charset>
    <response>
        <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>1</is_valid>
        <status>11</status>
        <status_text>Adressen är korrekt</status_text>
        <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>
    </response>
</api>

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

Address to validate¶

street	postalcode	locality
Drottninggatan 45	11121	Stockholm

Request¶

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

Response¶

JSON Response (response_format=json)

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

XML Response (response_format=xml)

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <name>Valid API Norden</name>
    <type>Address validation</type>
    <version>1.4</version>
    <charset>utf-8</charset>
    <response>
        <response_time>0,023</response_time>
        <query>
            <street>Drottninggatan 45</street>
            <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>1</is_valid>
        <status>11</status>
        <status_text>Adressen är korrekt</status_text>
        <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>
            <adm1_code>01</adm1_code>
            <adm1>Stockholm</adm1>
            <adm3_code>018001</adm3_code>
            <adm3>Stockholms domkyrkoförs.</adm3>
            <adm5_code>018001</adm5_code>
            <adm5>Stockholms domkyrkoförs.</adm5>
        </match>
    </response>
</api>

Validate - address¶

Endpoint URL¶

Supported parameters¶

Response¶

Query object¶

Interpretation object¶

Suggestion object¶

Match object¶

Error object¶

Examples¶

Example - Validation of a correct Swedish address¶

Address to validate¶

Request¶

Response¶

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

Address to validate¶

Request¶

Response¶

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

Address to validate¶

Request¶

Response¶

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