Van Postcode API 1.0 naar 2.0

Vanaf 1 maart aanstaande zal de oude versie van onze Postcode API niet meer beschikbaar zijn. Omdat we veel vragen krijgen van mensen die willen upgraden naar de nieuwe versie willen we in dit blog de grootste verschillen uitleggen om het zo eenvoudig mogelijk te maken om over te stappen. Bij een upgrade naar versie 2.0 dien je rekening te houden met onderstaande zaken.

#De API Key

De waarde van de oude API Key (die in 1.0 werd meegestuurd middels de Api-Key header) is niet meer geldig voor versie 2.0. Dit betekent dat je een nieuwe key dient aan te vragen via onze website http://www.postcodeapi.nu/#pakketten. Mocht je je pakket later willen upgraden dan kunnen wij dit altijd handmatig voor je doen middels een mailtje naar ons. Een ander verschil is dat de nieuwe API Key niet meer meegestuurd wordt met de Api-Key header, maar met een nieuwe header: X-Api-Key:

Oude request header Nieuwe request header
Api-Key X-Api-Key

#Het protocol

De oude versie was zowel beschikbaar zonder SSL als met SSLv3. Omdat beide methodes onveilig zijn kan versie 2.0 alléén benaderd worden via TLS.

Oude protocolNieuwe protocol
HTTP, SSLv3TLS

Als je een onveilige verbinding wil forceren kun je, indien de server dit toestaat, wellicht de verify peer optie van SSL disable. In PHP ziet dit er bijvoorbeeld zo uit:

curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);

#De collecties

Spraken we in versie 1.0 nog over postcodes, versie 2.0 retourneert momenteel enkel adressen. Dit betekent dat je op basis van filters, zoals ?postcode=6545CA, alle adressen in Nederland terugkrijgt die aan deze filters voldoen. Door vervolgens de straatnaam en de plaatsnaam van het eerste resultaat te nemen krijg je alsnog het juiste resultaat. De collectie met alle postcodes staat op onze roadmap en zorgt voor een eenvoudigere manier om dezelfde informatie boven water te krijgen.

#De URL's

De nieuwe API is volledig RESTful, wat wil zeggen dat de URL structuur er als volgt uitziet: [endpoint]/[collectie]/[id] gevolgd door mogelijke filters in de vorm van query parameters: ?postcode=6511AL, waarbij [id] optioneel is voor het geval je dat betreffende record wil ophalen en de optionele filters het zoeken door de collectie mogelijk maken.

Oude endpointNieuwe endpoint
https://api.postcodeapi.nuhttps://postcode-api.apiwise.nl

Hieronder volgen een paar voorbeeldcalls die uiteraard voorafgegaan moeten worden door het juiste endpoint (let op: het nieuwe endpoint werkt alleen via https en moet /v2 aan het begin van het pad bevatten.

Use caseOude padNieuwe pad
Ophalen van postcode 6545CA /6545CA /v2/addresses?postcode=6545CA
Ophalen van postcode + huisnummer combinatie 6545CA + 29 /6545CA/29 /v2/addresses?postcode=6545CA&number=29
Ophalen van één specifiek adres - /v2/addresses/0268200000054476

Het ophalen van één specifiek adres was voorheen hetzelfde als postcode + huisnummer combinatie, maar blijkt feitelijk onjuist te zijn. In de nieuwe versie krijgt ieder adres haar eigen record met het officiële [id] van de Nederlandse overheid, zoals https://postcode-api.apiwise.nl/v2/addresses/0268200000054476.

#De response

De responses zijn, net zoals in versie 1.0, nog steeds volledig JSON. Dit betekent dat je het object eenvoudig kunt parsen met de meeste programmeertalen. Wel is in versie 2.0 HAL geïntroduceerd. Dit is een standaard om door API collecties te kunnen navigeren en pagineren. De navigatie URL's zitten in het _links object, de data (bij collecties) in het _embedded object. Zie ook het voorbeeld onderaan deze pagina.

#GeoJSON

Een ander verschil met de response uit versie 1.0 is het gebruik van GeoJSON objecten om geografische informatie weer te geven. De X/Y (Rijksdriehoekstelsel) en de latitude/longitude (GPS) coördinaten kun je hier los uit een array halen (let op: lat, lon wordt in GeoJSON omgedraaid naar lon, lat), maar het hele GeoJSON object is ook compatible met veel standaard mapping tools zoals Open Streetmap. Je kunt testen wat er gebeurt door het onderstaande GeoJSON object in GeoJSON.io te plakken:

{
  "crs": {
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    },
    "type": "name"
  },
  "type": "Point",
  "coordinates": [
    5.80312065359,
    51.8453059862
  ]
}

#De status codes

In plaats van de property success: true maken we nu correct gebruik van de HTTP status codes. Als je een 200: OK terug krijgt weet je dat de call succesvol gelukt is. Krijg je een 404: Not found terug, dan heb je een call gedaan naar een URL die niet bestaat. De volgende status codes zijn momenteel geïmplementeerd:

  • 200 OK
  • 401 API key niet geldig
  • 404 Niet gevonden (alleen voor detail calls: /addresses/[id])
  • 429 Limiet overschreden (alleen voor gratis accounts)
  • 500 Unknown server error

#Voorbeeld

In het onderstaande voorbeeld halen we de gegevens van de postcode 6545CA op volgens de oude en de nieuwe versie.

#De oude versie (1.0)

URL:

https://api.postcodeapi.nu/6545CA

Request Headers:

Api-Key: jouw-oude-api-key

Response:

{
  "success": true,
  "resource": {
    "street": "Binderskampweg",
    "postcode": "6545CA",
    "town": "Nijmegen",
    "municipality": "Nijmegen",
    "province": "Gelderland",
    "latitude": 51.8453169492,
    "longitude": 5.8032152542,
    "x": 183666,
    "y": 428613
  }
}

Parse voorbeeld in PHP:

$object = json_decode($response);
$street= $object->resource->street;
$town = $object->resource->town;
$latitude = $object->resource->latitude;
$longitude = $object->resource->longitude;
$...

#Versie 2.0

URL (alléén te bereiken via TLS):

https://postcode-api.apiwise.nl/v2/addresses?postcode=6545CA

Request Headers:

X-Api-Key: jouw-nieuwe-api-key

Response:

{
  "_embedded": {
    "addresses": [
      {
        "city": {
          "id": "3030",
          "label": "Nijmegen"
        },
        "letter": null,
        "id": "0268200000054476",
        "purpose": "industriefunctie",
        "postcode": "6545CA",
        "municipality": {
          "id": "0268",
          "label": "Nijmegen"
        },
        "nen5825": {
          "street": "BINDERSKAMPWEG",
          "postcode": "6545 CA"
        },
        "street": "Binderskampweg",
        "number": 1,
        "province": {
          "id": "25",
          "label": "Gelderland"
        },
        "addition": null,
        "geo": {
          "center": {
            "wgs84": {
              "crs": {
                "properties": {
                  "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
                },
                "type": "name"
              },
              "type": "Point",
              "coordinates": [
                5.80584483439,
                51.8435489279
              ]
            },
            "rd": {
              "crs": {
                "properties": {
                  "name": "urn:ogc:def:crs:EPSG::28992"
                },
                "type": "name"
              },
              "type": "Point",
              "coordinates": [
                183849.179,
                428412.624
              ]
            }
          }
        },
        "type": "Verblijfsobject",
        "_links": {
          "self": {
            "href": "https://postcode-api.apiwise.nl/v2/addresses/0268200000075146/"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://postcode-api.apiwise.nl/v2/addresses/?postcode=6545CA"
    },
    "next": {
      "href": "https://postcode-api.apiwise.nl/v2/addresses/?postcode=6545CA&from[number]=29&from[id]=0268200000075146&from[postcode]=6545CA"
    }
  }
}

Parse voorbeeld in PHP:

$object = json_decode($response);

// addresses is een array met 0 of meerdere adres objecten erin
$addresses = $object->_embedded->addresses;

// hier kun je overheen lopen
foreach ($addresses as $address) {...

// of het eerste adres pakken (als deze er is!)
$address = $addresses[0];

$street = $address->street;
$city = $address->city->label;

// de coördinaten zitten in een array in het GeoJSON object
$geoJson = $address->geo->center->wgs84;
$latitude = $geoJson->coordinates[1];
$longitude = $geoJson->coordinates[0];
$...

#Vragen?

Voor vragen en/of opmerkingen kun je gebruik maken van Disqus onderaan deze pagina of je kunt een issue inschieten op ons Github kanaal: https://github.com/apiwise/postcodeapi/issues. De officiële documentatie vind je hier: http://www.postcodeapi.nu/docs/ en SDK's zijn te downloaden via Swaggerhub: https://swaggerhub.com/api/apiwise/postcode-api/2.0.