Postcode API 2.1 gereleased

Vandaag is er een nieuwe versie van de Postcode API online gegaan. De 2.1 release bevat een aantal langverwachte nieuwe features zoals de /postcodes call, het zoeken op P4 en inzicht in de aantallen reeds gemaakte en resterende calls om beter om te kunnen gaan met rate limiting. Daarnaast zijn er een aantal performance verbeteringen doorgevoerd, is de data kwaliteit verbeterd en de documentatie uitgebreid. Bovendien is deze versie volledig backwards compatible, wat betekent dat iedereen zonder risico op kapotte implementaties automatisch geüpgraded is. Hieronder een overzicht van de nieuwe features.

#Rate limiting (#27)

Om beter inzicht te krijgen in het verbruik van de API zijn er twee nieuwe response headers geïntroduceerd:

  • X-RateLimit-Limit: geeft het aantal calls per dag aan bij het betreffende pakket (500 voor het gratis abonnement).
  • X-RateLimit-Remaining: geeft het aantal resterende calls voor die dag aan. Als hier overheen gegaan wordt zal het gratis pakket geen response meer geven (hard-limit), bij betaalde pakketten blijft de API gewoon werken (soft-limit).

#Postcodes call (#26, #32, #38)

Naast de /addresses call is er nu ook een /postcodes call, waar eenvoudig naar postcodes (P6: 1234AB) en postcode gebieden (P4: 1234) gezocht kan worden. De call /postcodes retourneert een gepagineerde collectie met alle postcodes in Nederland, de call /postcodes/1234AB geeft slechts één postcode terug en met de postcodeArea parameter zijn de resultaten uit de collectie te filteren op P4 niveau: /postcodes?postcodeArea=1234. Elke postcode heeft de volgende eigenschappen:

  • Plaats (object met BAG id en label).
  • Gemeente (object met BRP id en label).
  • Provincie (object met BRP id en label).
  • Straatnamen (array van strings, aangezien er meerdere straten onder één postcode kunnen vallen).
  • De NEN 5825 notaties van deze straatnamen.
  • Een GeoJSON object met de latitude en longitude van het middelpunt van de postcode.

#Data kwaliteit (#23, #28)

Af en toe komt het voor dat een adres niet gevonden kan worden, terwijl deze wel degelijk bestaat. Meestal komt dit doordat het adres officieel (volgens de overheidsinformatie van de BAG) niet bestaat, maar in sommige gevallen was dit een foute interpretatie in onze conversiescripts. De brondata bestaat namelijk uit een heleboel relaties, statusvelden, ingangsperioden, etc. Wij zijn hier dieper in gedoken en hebben aan de hand van tests met de gerapporteerde uitzonderingssituaties onze conversiescripts aangepast zodat de kans op een dergelijk incident nog kleiner is geworden. Daarnaast hebben we een tweetal attributen toegevoegd aan een address response:

  • year: het bouwjaar van het pand.
  • exterior: een GeoJSON object met de geometrie van de omtrek van het pand. Alleen beschikbaar voor een enkel adres vanwege de omvang van het object.

#Documentatie (#36, #42)

De API documentatie is uitgebreid met juiste beschrijvingen van de verschillende status codes die terug kunnen komen en betere voorbeeldcode. Tevens zijn mogelijke foutmeldingen in de API zelf verbeterd zodat nog het eenvoudiger wordt om de API snel te implementeren. De mogelijke statuscodes die nu terugkomen zijn:

  • 200: OK.
  • 401: API key ontbreekt of is niet geldig.
  • 404: Niet gevonden.
  • 415: Ongeldige Content-Type.
  • 429: Limiet overschreden.

Voor de meest actuele documentatie en SDK's in verschillende programmeertalen waar men snel mee uit de voeten kan verwijzen we je graag door naar onze bijgewerkte Swaggerhub pagina: https://swaggerhub.com/api/apiwise/postcode-api.

#Performance

Algemene aanpassingen aan de code, upgrades van gebruikte software componenten en wijzigingen aan de architectuur zorgen voor verbeterde response tijden en brengen het risico op downtime nog verder omlaag, wat de Postcode API een uiterst betrouwbare oplossing maakt voor bedrijfskritieke toepassingen. Tevens hebben deze aanpassingen 'onder de motorkap' ertoe geleid dat het uitvoeren van updates eenvoudiger te realiseren en naar productie te brengen is, waardoor volgende releases sneller doorontwikkeld kunnen worden.

#Abonnement upgraden

Wil je naar aanleiding van deze release je abonnement upgraden? Neem dan contact met ons op via info@apiwise.nl zodat wij je API Key kunnen overhevelen naar een ander pakket. Betaling kan maandelijks per creditcard of jaarlijks op factuur.

#Github

Heb je zelf suggesties voor onze API of wil je een bug rapporteren? Maak dan een issue aan op onze Github pagina: https://github.com/apiwise/postcodeapi. Milestone 2.2 is inmiddels alvast aangemaakt, op naar de volgende release!