Validate Locality

Endpoint URL

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

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

Parameters

Query parameter	Description
`locality`	Required. The locality (city). Example: `locality=Stockholm`
`response_format`	`json` (default) or `xml`.
`administrative`	`true` adds administrative divisions. Needs a permission. The codes are those of one address in the locality; a large locality spans several parishes and districts but gets one set.
`coordinate`	`true` adds the locality's centre point as `latitude` and `longitude`. Needs a permission.

For Finland, use the Finnish name (Helsinki); Swedish names are not validated.

Response

Key	Type	Description
`version`	String	API version
`response_time`	Float	Processing time in seconds
`query`	Object	`locality` as received
`interpretation`	Object	`locality` as parsed
`is_valid`	Boolean	`true` when the locality exists
`status`	Integer	`302` valid, `300` suggestions, `404` nothing found, `400` bad request. See Response status
`match`	Array	When the locality is valid: one object with `locality` and `address_type`
`suggestions`	Array	When it is not valid: similar localities, each with `errors`
`errors`	Object	Error code → text. Needs the error-codes permission

Error codes for localities: 400 Locality is missing, 401 Unknown format for locality, 402 Incorrect locality, 403 Locality had abbreviations, 404 Locality had minor errors that were corrected. See Glossary.

Examples

A valid locality

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

{
  "version": "2.0",
  "response_time": 0.0028,
  "query": {
    "locality": "Stockholm"
  },
  "interpretation": {
    "locality": "stockholm"
  },
  "is_valid": true,
  "status": 302,
  "match": [
    {
      "address_type": "BB",
      "locality": "Stockholm"
    }
  ]
}

A misspelled locality

curl -G https://app-api.geposit.se/v2.0/validate/locality/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "locality=Stickholm"

{
  "version": "2.0",
  "response_time": 0.0105,
  "query": {
    "locality": "Stickholm"
  },
  "interpretation": {
    "locality": "stickholm"
  },
  "is_valid": false,
  "status": 300,
  "errors": {
    "402": "Incorrect locality"
  },
  "suggestions": [
    { "address_type": "BB", "locality": "Stockholm", "errors": [402] },
    { "address_type": "BB", "locality": "Stockholm-Arlanda", "errors": [402] },
    { "address_type": "BB", "locality": "Stockholm-Globen", "errors": [402] }
  ]
}

<Validate>
  <version>2.0</version>
  <response_time>0.0105</response_time>
  <query>
    <locality>Stickholm</locality>
  </query>
  <interpretation>
    <locality>stickholm</locality>
  </interpretation>
  <is_valid>false</is_valid>
  <status>300</status>
  <errors>
    <code>402</code>
    <message>Incorrect locality</message>
  </errors>
  <suggestions>
    <address_type>BB</address_type>
    <locality>Stockholm</locality>
    <errors>402</errors>
  </suggestions>
  <suggestions>
    <address_type>BB</address_type>
    <locality>Stockholm-Arlanda</locality>
    <errors>402</errors>
  </suggestions>
  <suggestions>
    <address_type>BB</address_type>
    <locality>Stockholm-Globen</locality>
    <errors>402</errors>
  </suggestions>
</Validate>