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

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).

https://api.spikkl.nl/geo/nld/lookup.json?key=API_KEY&postal_code=2611KL&street_number=15

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.

Suggestions

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).

https://api.spikkl.nl/geo/nld/lookup.json?key=API_KEY&postal_code=2628EG&street_number=13

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.

Results

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.