Validate Address

Endpoint URL

GET https://app-api.geposit.se/v2.0/validate/address/{COUNTRY_CODE}

{COUNTRY_CODE} is se, no, dk, fi or ax. Authentication, response status and permissions are described in Valid Intro. Full reference: Validate Address.

Parameters

Send street or query. Add postcode and locality whenever you have them: the address is checked against all three, and without them more addresses match.

Query parameter	Description
`street`	The street address, either in full (`street=Storgatan 12B`, `street=Gullyckeskärsvägen 203-28`) or only the street name with the number in the parameters below.
`street_number`	Street number, when it is not part of `street`. Example: `street=Storgatan&street_number=12`
`letter`	Letter of the street number, when it is not part of `street`. Example: `street=Storgatan&street_number=12&letter=B`
`extra_number`	Secondary street number, when it is not part of `street`. Example: `street=Gullyckeskärsvägen&street_number=203&extra_number=28`
`postcode`	Postcode of the address. Example: `postcode=11121`
`locality`	Locality (city) of the address. Example: `locality=Stockholm`
`query`	The whole address as free text, instead of the fields above. Example: `query=Drottninggatan 45, 111 21 Stockholm`. If you send both, the separate fields win.
`suggestions`	`true` (default) returns suggestions when the address is invalid. `false` returns only the verdict and the errors.
`response_format`	`json` (default) or `xml`.
`administrative`	`true` adds administrative divisions. Needs a permission.
`coordinate`	`true` adds `latitude` and `longitude`. Needs a permission.
`property_designation`	`true` adds the property designation (fastighetsbeteckning), Sweden. Needs a permission.
`uuid`	`true` adds the address's unique id, Sweden only. Needs a permission.
`deso`	`true` adds `deso_code`, Sweden. Needs a permission.
`regso`	`true` adds `regso_code` and `regso_name`, Sweden. Needs a permission.
`neighborhood`	`true` adds `neighborhood_1_name` and `neighborhood_2_name`. Needs a permission.

A parameter that needs a permission your key does not have is ignored. See Permissions.

Response

Key	Type	Description
`version`	String	API version
`response_time`	Float	Processing time in seconds
`query`	Object	The parameters as received
`interpretation`	Object	How the input was parsed: `street`, `street_number`, `letter`, `extra_number`, `postcode`, `locality`
`is_valid`	Boolean	`true` when the address matches exactly one address with no errors
`status`	Integer	`302` valid, `300` suggestions, `404` nothing found, `200` invalid with `suggestions=false`, `400` bad request. See Response status
`status_text`	String	Reason for a `400`
`match`	Array	When the address is valid: an array with one address object
`suggestions`	Array	When the address is invalid: zero or more address objects
`errors`	Object	What was wrong with the input, as error code → text. Needs the error-codes permission. See Glossary

Address object

Used in match and suggestions. Empty fields are left out.

Key	Type	Description
`address_type`	String	See Address types
`street`	String	Street name
`street_number`	String	Street number
`letter`	String	Letter of the street number, for example `B` in Storgatan 12B
`extra_number`	String	Secondary street number, for example `28` in Gullyckeskärsvägen 203-28
`postcode`	String	Postcode
`locality`	String	Locality
`status`	String	`OK` when this address has no errors
`errors`	Array	Error codes for this suggestion, for example `[302]`. Needs the error-codes permission
`adm1_code` … `adm5_code`, `adm1_name` … `adm5_name`	String	Administrative divisions, with `administrative=true`. See Glossary
`latitude`, `longitude`	Float	Coordinate, with `coordinate=true`
`property_designation`	String	With `property_designation=true`
`uuid`	String	With `uuid=true`
`deso_code`	String	With `deso=true`
`regso_code`, `regso_name`	String	With `regso=true`
`neighborhood_1_name`, `neighborhood_2_name`	String	With `neighborhood=true`

Finland

Validate Address expects the Finnish names. A Swedish name such as Mannerheimvägen 1, Helsingfors is not accepted as valid; the Finnish form (Mannerheimintie 1, Helsinki) is returned as a suggestion. Suggest Address does find addresses by their Swedish names.

Examples

A valid address

curl -G https://app-api.geposit.se/v2.0/validate/address/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "street=Drottninggatan 45" \
  --data-urlencode "postcode=11121" \
  --data-urlencode "locality=Stockholm"

{
  "version": "2.0",
  "response_time": 0.0135,
  "query": {
    "street": "Drottninggatan 45",
    "postcode": "11121",
    "locality": "Stockholm"
  },
  "interpretation": {
    "street": "drottninggatan",
    "street_number": "45",
    "postcode": "11121",
    "locality": "stockholm"
  },
  "is_valid": true,
  "status": 302,
  "match": [
    {
      "address_type": "NB",
      "street": "Drottninggatan",
      "street_number": "45",
      "postcode": "11121",
      "locality": "Stockholm",
      "status": "OK"
    }
  ]
}

The same request with response_format=xml:

<Validate>
  <version>2.0</version>
  <response_time>0.0068</response_time>
  <query>
    <street>Drottninggatan 45</street>
    <postcode>11121</postcode>
    <locality>Stockholm</locality>
  </query>
  <interpretation>
    <street>drottninggatan</street>
    <street_number>45</street_number>
    <postcode>11121</postcode>
    <locality>stockholm</locality>
  </interpretation>
  <is_valid>true</is_valid>
  <status>302</status>
  <match>
    <address_type>NB</address_type>
    <street>Drottninggatan</street>
    <postcode>11121</postcode>
    <locality>Stockholm</locality>
    <status>OK</status>
    <street_number>45</street_number>
  </match>
</Validate>

A wrong postcode

The address exists, but in postcode 11121, not 11122:

curl -G https://app-api.geposit.se/v2.0/validate/address/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "street=Drottninggatan 45" \
  --data-urlencode "postcode=11122" \
  --data-urlencode "locality=Stockholm"

{
  "version": "2.0",
  "response_time": 0.0172,
  "query": {
    "street": "Drottninggatan 45",
    "postcode": "11122",
    "locality": "Stockholm"
  },
  "interpretation": {
    "street": "drottninggatan",
    "street_number": "45",
    "postcode": "11122",
    "locality": "stockholm"
  },
  "is_valid": false,
  "status": 300,
  "errors": {
    "302": "Postal code is incorrect"
  },
  "suggestions": [
    {
      "address_type": "NB",
      "street": "Drottninggatan",
      "street_number": "45",
      "postcode": "11121",
      "locality": "Stockholm",
      "status": "OK",
      "errors": [302]
    }
  ]
}

With suggestions=false the same request returns only the verdict:

{
  "version": "2.0",
  "response_time": 0.0159,
  "query": { "street": "Drottninggatan 45", "postcode": "11122", "locality": "Stockholm" },
  "interpretation": { "street": "drottninggatan", "street_number": "45", "postcode": "11122", "locality": "stockholm" },
  "is_valid": false,
  "status": 200,
  "errors": {
    "302": "Postal code is incorrect"
  }
}

In XML, the top-level errors are repeated <errors><code>302</code><message>Postal code is incorrect</message></errors> elements, and a suggestion's errors are <errors>302</errors>.

A misspelled street

curl -G https://app-api.geposit.se/v2.0/validate/address/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "street=Drotninggatan 45" \
  --data-urlencode "postcode=11121" \
  --data-urlencode "locality=Stockholm"

{
  "is_valid": false,
  "status": 300,
  "errors": {
    "202": "Street address had misspellings, errors or was incorrect",
    "260": "Missing letter in the street number"
  },
  "suggestions": [
    {
      "address_type": "NB",
      "street": "Drottninggatan",
      "street_number": "45",
      "postcode": "11121",
      "locality": "Stockholm",
      "status": "OK",
      "errors": [202]
    },
    {
      "address_type": "NB",
      "street": "Drottninggatan",
      "street_number": "45",
      "letter": "T",
      "postcode": "11121",
      "locality": "Stockholm",
      "errors": [202, 260]
    }
  ]
}

(version, response_time, query and interpretation left out.)

Administrative divisions and coordinate

Add administrative=true&coordinate=true to the first example (needs both permissions). The match then includes:

{
  "address_type": "NB",
  "street": "Drottninggatan",
  "street_number": "45",
  "postcode": "11121",
  "locality": "Stockholm",
  "adm1_code": "01",
  "adm2_code": "0180",
  "adm3_code": "018001",
  "adm4_code": "215020",
  "adm5_code": "018001",
  "adm1_name": "Stockholm",
  "adm2_name": "Stockholm",
  "adm3_name": "Stockholms domkyrkoförsamling",
  "adm4_name": "Stockholms domkyrkodistrikt",
  "adm5_name": "Stockholms domkyrkoförs.",
  "latitude": 59.33245,
  "longitude": 18.06225,
  "status": "OK"
}