Geocode - locality¶
Endpoint for checking if an locality in a specific country is valid or not.
Endpoint URL¶
(POST | GET) https://valid.geposit.se/1.7/geocode/locality/{COUNTRY_CODE}
{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 |
locality | Required The locality to geocode. Example: locality=Stockholm |
response_format | Sets the format for the API response. The following values are supported: - xml - json (Default value) |
lang | Control the language used in response output (status, errors etc.) : - se - Swedish (Default)- no - Norweigan- dk - Danish- fi - Finish- en - English |
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 locality |
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 locality input - declared as a query object (referenced below) |
response » interpretation | Object | Object containing the parsed version of the incoming locality - declared as a interpretation object (referenced below) |
response » is_valid | Integer | States if the sent in locality is valid or not. Possible values are: - 0 (Not valid)- 1 (Valid) |
response » errors | Object | Error(s) detected in the locality - declared as an error object (referenced below) |
response » match | Object | If the locality is correct - this object will hold a detailed description of the matched locality - declared as an match object (referenced below) |
Query object¶
Key | Value type | Value description |
---|---|---|
locality | String | The locality sent for validation formatted as in the request input parameter |
Interpretation object¶
Key | Value type | Value description |
---|---|---|
locality | String | Parsed locality / city |
Match object¶
Key | Value type | Value description |
---|---|---|
locality | String | Locality / city |
x_lon | Float | X / Longitude (WGS84 - EPSG:4326) |
y_lat | Float | Y / Latitude (WGS84 - EPSG:4326) |
Error object¶
A key/value based object holding all the errors that were found with the incoming locality. Each key represent an error code and the value for that key gives you a textual representation of that error.
Possible error codes¶
Code | Explanation |
---|---|
300 | Locality is missing |
301 | Unknown format for the locality |
302 | Incorrect locality |
Examples¶
Example - Validation of a correct Swedish locality¶
Request¶
curl https://valid.geposit.se/1.7/geocode/locality/se -d "locality=Stockholm&response_format=json&api_key={API_KEY}"
Response¶
{
"name": "Valid API Norden",
"type": "Geocode locality",
"version": "latest",
"charset": "utf-8",
"response": {
"response_time": 0.21,
"query": {
"locality": "Stockholm"
},
"interpretation": {
"locality": "Stockholm"
},
"is_valid": 1,
"match": {
"locality": "Stockholm",
"x_lon": 18.0738389491925,
"y_lat": 59.3314899658277
}
}
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
<name>Valid API Norden</name>
<type>Geocode locality</type>
<version>latest</version>
<charset>utf-8</charset>
<response>
<response_time>0,171</response_time>
<query>
<locality>Stockholm</locality>
</query>
<interpretation>
<locality>Stockholm</locality>
</interpretation>
<is_valid>1</is_valid>
<match>
<locality>Stockholm</locality>
<x_lon>18,073838949192</x_lon>
<y_lat>59,331489965828</y_lat>
</match>
</response>
</api>
Example - Validation of an invalid Swedish locality¶
Request¶
curl https://valid.geposit.se/1.7/geocode/locality/se -d "locality=Stickholm&response_format=json&api_key={API_KEY}"
Response¶
{
"name": "Valid API Norden",
"type": "Geocode locality",
"version": "latest",
"charset": "utf-8",
"response": {
"response_time": 0.168,
"query": {
"locality": "Stickholm"
},
"interpretation": {
"locality": "Stickholm"
},
"is_valid": 0,
"errors": {
"402": "Felaktig postort"
}
}
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
<name>Valid API Norden</name>
<type>Geocode locality</type>
<version>latest</version>
<charset>utf-8</charset>
<response>
<response_time>0,256</response_time>
<query>
<locality>Stickholm</locality>
</query>
<interpretation>
<locality>Stickholm</locality>
</interpretation>
<is_valid>0</is_valid>
<errors>
<error>
<error_code>402</error_code>
<error_text>Felaktig postort</error_text>
</error>
</errors>
</response>
</api>