Helemaal de weg kwijt?

We helpen je op weg om een vliegende start te maken met de Spikkl adresvalidatie. Lukt het even niet, vraag om hulp en we helpen je zo snel mogelijk verder.


Response format

The response form of the API is formatted according to the value of the format parameter in the request URL. All coordinates use the WGS84 reference coordinate system.

The following example, the Spikkl API requests a json response for a query on "2611KL 15" in The Netherlands (nld).


The JSON returned by the Spikkl API will look like:

  "results": [
      "location_id": "5e405237ec42128617dfb57f",
      "postal_code": "2611KL",
      "street_number": 15,
      "street_number_suffix": null,
      "street_name": "Trompetstraat",
      "city": "Delft",
      "municipality": "Delft",
      "administrative_areas": [
          "type": "province",
          "name": "Zuid-Holland",
          "abbreviation": "ZH"
      "country": {
        "iso3_code": "NLD",
        "iso2_code": "NL",
        "name": "Nederland"
      "centroid": {
        "latitude": 52.01293,
        "longitude": 4.362023
      "formatted_address": "Trompetstraat 15, 2611KL Delft, Nederland",
      "match": "exact"
  "status": "ok",
  "meta": {
    "timestamp": 1569305003595,
    "trace_id": "c8e52fa510d4b47d8f16e682"

Note that the JSON response contains three root elements:

  • status contains the status code of the request.
  • results contains an array of address information and geometry information.
  • meta contains meta data of the request.

Generally, only one entry is returned in the results array for address lookup. The API may return more results.

Status codes

The status field of the contains the status of the request and may contain debugging information. The following values may occur:

Status code Http code Description
"OK" 200 Indicates that no error occurred and at least one result was returned.
"ZERO_RESULTS" 404 Indicates that the request was successful, however no results were found. There may be passed an non-existent location.
"QUOTA_REACHED" 429 Indicates that the monthly request quota reached, that your self-imposed quota has been reached or that billing is not enabled for the used API key.
"INVALID_API_KEY" 401 Indicates that the api key provided is invalid or missing.
"INVALID_REQUEST" 400 Indicates an invalid request, generally due to missing parameter postal_code, latitude, and/or longitude.
"ACCESS_RESTRICTED" 403 Indicates that the api is restricted and that the origin not matches those restrictions.
"OUT_OF_RANGE" 400 Indicates an invalid request where the provided coordinate is outside the requested country.
"UNKNOWN_ERROR" 500 Indicates that the request could not be processed due to an server error. You may try again.


When the Spikkl API returns the status code "ZERO_RESULTS", the response object might contain a suggestion field. The suggestion object provides key-based suggestions for the given request.

The following example, the Spikkl API requests a json response for a query on "2628EG 13" in The Netherlands (nld).


The JSON returned by the Spikkl API will look like:

  "status_code": "ZERO_RESULTS",
  "status": "failed",
  "suggestions": {
    "street_number_suffix": "A"

Error messages

When the Spikkl API returns a status code, other than "OK", there may be an additional message field in the response object. This field contains additional information of the status code.


Attribute Description
postal_code A four digit neighbourhood code plus two character letter combination. Does not contain SA, SD, or SS.
street_number The house number of an address location. Numeric, between 0 and 99999.
street_number_suffix The house number addition, at most 6 characters, may contain a space after the first character.
street_name The street name corresponding with the postal code, at most 80 characters long.
city Official city name, at most 80 characters.
municipality The overarching administrative area for the city, contains at most 80 characters.
administrative_areas The administrative area(s) overarching the municipality, typically of type province, region, arrondissement.
country The country the address location is in: combination of iso coding and country name.
centroid The longitude latitude combination of the center location of the address.