Valid Intro
Valid API Introduction
Valid ensures correct addresses - and is quick and easy to integrate
Valid API helps you to:
- Insert correct addresses through autocomplete suggestions (Suggest) and
- Validate the correctness of the inserted address (Validate)
Most companies implement both features, but it is possible to use only one of them. To check many postcodes in one request, use Validate Multi Postcode.
The API integration is simple and should take less than 6 hours to complete.
Authentication
Pass your API key in the x-api-key request header (recommended):
curl -G https://app-api.geposit.se/v2.0/validate/postcode/se \
-H "x-api-key: {API_KEY}" \
--data-urlencode "postcode=11121"You can also pass it as the api_key query parameter, but a key in a URL is easier to leak through logs and browser history.
| Problem with the key | Response |
|---|---|
| No key, or an unknown key | HTTP 401, empty body |
| The key does not include this product | HTTP 403, JSON body with message and required_one_of |
| The key is deactivated | HTTP 200 with "status": 403 in the body |
Countries
Every endpoint takes the country as the last part of the path, for example /v2.0/validate/address/se. Use the lower-case ISO code:
| Code | Country |
|---|---|
se | Sweden |
no | Norway |
dk | Denmark |
fi | Finland |
ax | Åland |
Other values, including upper-case codes such as SE, are not rejected, but do not return data for the country you meant.
Response status
Always check the status field in the response body. Apart from the authentication errors above, the API answers HTTP 200 and puts the result in status:
status | Meaning |
|---|---|
302 | Exactly one match |
300 | One or more suggestions |
404 | Nothing found |
400 | Bad request. status_text says why |
200 | Validate Address with suggestions=false on an invalid address: no match and no suggestions are returned |
Two exceptions return HTTP 400 as well as "status": 400: Suggest requests without query, and a Validate Multi Postcode body that is not valid JSON in the expected shape.
Each match and suggestion can also carry its own "status": "OK" field. It describes that single item and is not the response status.
See Glossary for the detailed error codes.
Permissions
Some parameters need an extra permission on your API key. Without the permission the parameter is ignored and no error is returned, so the response simply lacks those fields.
| Parameter or field | Returns |
|---|---|
administrative | Administrative divisions (adm1_code … adm5_name) |
coordinate | latitude and longitude |
property_designation | Property designation (fastighetsbeteckning), Sweden |
uuid | Unique address id, Sweden only |
deso, regso | Statistical areas DeSO and RegSO, Sweden |
neighborhood | Neighbourhood names |
errors (detailed error codes) | The errors object and the per-item errors lists |
Contact us at [email protected] to add a permission to your key.
Response formats
Empty fields are left out of responses, and a response can contain fields that are not described in these Guides; ignore those.
All endpoints answer JSON by default. Add response_format=xml for XML; Suggest endpoints also support response_format=text. In XML the root element is <Validate> or <Suggest>.
API reference
Each endpoint is also described in the API reference, where you can try it out.
Updated about 7 hours ago