Nieuwe versie BRK-DKK API per 11 juli

Vandaag (11 juli) hebben wij de BRK-DKK REST API gemigreerd naar onze nieuwe architectuur. De nieuwe API is voor zover mogelijk backwards compatible met de vorige versie en daarom uitgerold als versie 1.1. In de praktijk zien we dat er toch wat kleine verschillen in de API’s zitten die we op basis van de OpenAPI specificaties niet hadden gezien, maar daardoor ook wat lastig te verhelpen zijn.

In de nieuwe versie van de API zitten een paar verschillen met de vorige:

  • Er wordt in een aantal velden die tot nu toe leeg werden teruggegeven nu ook daadwerkelijk data terug gegeven
  • Er is een nieuw endpoint toegevoegd: percelen/_zoek, dit endpoint is de opvolger van het PUT endpoint
  • Het PUT endpoint is deprecated, maar blijft voorlopig wel beschikbaar zodat iedere gebruiker op zijn tempo de overstap kan maken. Op een later moment zullen we aankondigen wanneer we het PUT endpoint uit gaan faseren.

De nieuwe API documentatie is te vinden op: https://brk.basisregistraties.overheid.nl/restful-api?articleid=1930301

De body van een aanroep van het nieuwe percelen/_zoek endpoint moet er als volgt uitzien:

{
  "geometry": {
    "intersects": {
      "type": "Point",
      "coordinates": [6.236751, 52.781689]
    }
  }
}
1 like

Ik krijg onderstaande foutmeldingen als ik op Datamodel in

https://brk.basisregistraties.overheid.nl/datamodel?articleid=1930301
klik (Chrome en Safari Mac OSX 10.11.6)

Ik krijg het ook niet voor elkaar. Er vanuit gaande dat het bovenstaande voorbeeld een typfout betreft (intersect op Point type), en uitgaande van de documentatie waar naar verwezen werd, zou het request

{
	"geometry":  {
		"contains":  {
			"type": "Point", 
			"coordinates": [ 6.236751, 52.781689 ] 
		} 
	} 
}

Geaccepteerd moeten worden. De server geeft dan ook geen foutmelding, maar het resultaat is totaal ongerelateerd. Ik krijg percelen terug die in verschillende gemeenten in een heel ander deel van het land liggen. Het komt mij voor alsof dit het begin van een lijst van alle percelen betreft.

En omdat ik het toch graag even wil vermelden; ik maak al meer dan een half jaar op semi-dagelijkse basis dankbaar gebruik van jullie API. Sinds gisteren echter, liggen al mijn programma’s in de kreukels. Ik vrees dat de migratie met oog op backward-compatibility toch niet helemaal vlekkeloos verlopen is.

@Anne Ik heb een request (POST) op https://brk.basisregistraties.overheid.nl/api/v1/percelen/_zoek gedaan met het door jou gedeelde body. Dat geeft mij het volgende resultaat:

                "kadastraleGemeentecode": "HVT03",
                "kadastraleGemeentenaam": "Havelte",
                "kadastraleGrootte": 285,
                "perceelnummer": 3280,
                "perceelnummerRotatie": 0,
                "sectie": "I",
                "soortGrootte": null,
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                6.23669819165058,
                                52.78157911191059
                            ],
                            [
                                6.236726753472676,
                                52.78157912391989
                            ],
                            [
                                6.236859513927741,
                                52.781579210600285
                            ],
                            [
                                6.236859505638412,
                                52.7818118068452
                            ],
                            [
                                6.236697171794016,
                                52.781811562583435
                            ],
                            [
                                6.23669819165058,
                                52.78157911191059
                            ]
                        ]
                    ]
                }

Dit is een perceel met een geometrie die het meegegeven punt bevat (contains dus).

Dat is inderdaad het resultaat dat ik verwacht. Ik zal nog even wat dieper graven.
Bedankt voor de bevestiging in ieder geval.

Om nog even in te gaan op je andere punt. Een intersect met een Point is geen typfout.

Intersects:
Returns TRUE if the Geometries “spatially intersect in 2D” - (share any portion of space) and FALSE if they don’t (they are Disjoint).

Je gaat dus op zoek naar een perceel met een geometrie die snijdt met het meegeven punt.

Contains geeft percelen terug met een geometrie waarbinnen het meegegeven punt ligt. Als het punt op de “rand” van een perceel ligt, zal een contains dit perceel niet als resultaat geven (een intersect wel)

Okey, duidelijk. Thanks.

Ik heb nog een eind om zitten rommelen, maar helaas zonder wenselijk resultaat.
Ik heb alle informatie die ik zo bijeen kan rapen vanuit mijn programma op een rijtje gezet. Om te voorkomen dat het mis gaat omdat ik iets simpels over het hoofd zie (zoals, frustrerend genoeg, niet geheel onvoorstelbaar in dit vakgebied) heb ik hieronder de C# code die die output gegenereerd heeft. Daaronder de informatie zoals die in de bestanden beland is en er uit gehaald is op dat breakpoint.

try {
    HttpRequestMessage req = new HttpRequestMessage(HttpMethod.Post, url);
    req.Headers.Add("Accept", "application/hal+json");
    req.Headers.Add("X-Api-Key", "********-****-****-****-5f6ebf41c072");
    req.Content = new StringContent(json.Replace(Environment.NewLine,""), Encoding.UTF8, "application/json");
    using (var sw = new StreamWriter(@".\Request.TXT"))
        sw.Write("Request Message:\n" + req + "\nContent:\n" + req.Content.ReadAsStringAsync().Result);
    response = client.SendAsync(req).Result;//   .PostAsync(url, new StringContent(json, Encoding.UTF8, "application/json")).Result;
    result = response.Content.ReadAsStringAsync().Result;
    using (var sw = new StreamWriter(@".\Response.TXT"))
        sw.Write("Response:\n" + response + "\nContent:" + result);
    Console.ReadLine();
} catch (WebException e) {
    EventMessage("Unexpected reply from server.\n\nReply:\n" + response + "\n\nException:\n" + e);
}

De output van dit stuk code beland dus in de twee bestanden Request.TXT en Response.TXT.
Dit is de het request:

Request Message:
Method: POST 
RequestUri: 'https://brk.basisregistraties.overheid.nl/api/v1/percelen/_zoek'
Version: 1.1
Content: System.Net.Http.StringContent
Headers:
{
  Accept: application/hal+json
  X-Api-Key: ********-****-****-****-5f6ebf41c072
  Content-Type: application/json; charset=utf-8
  Content-Length: 89
}
Content:
{"geometry": {"contains": {"type": "Point", "coordinates": [  6.236751,  52.781689] } } }

En dit is (een deel van) de reply:

Response:
StatusCode: 200, ReasonPhrase: '', Version: 1.1, Content: System.Net.Http.StreamContent, Headers:
{
  Strict-Transport-Security: max-age=31536000;
  X-Frame-Options: SAMEORIGIN
  Access-Control-Expose-Headers: x-pagination-limit, x-pagination-page, content-crs
  Access-Control-Allow-Origin: *
  X-Request-ID: 9afb2247-9b10-4638-a824-536ba5b5b80b
  Content-Crs: epsg:4258
  X-Pagination-Limit: 10
  X-Pagination-Page: 1
  X-Cnection: close
  Transfer-Encoding: chunked
  Date: Thu, 12 Jul 2018 14:58:58 GMT
  Server: nginx
  Content-Type: application/hal+json
}
Content:{
  "_embedded" : {
    "results" : [ {
      "kadastraleGemeentecode" : "TNZ00",
      "kadastraleGemeentenaam" : "Terneuzen",
      "kadastraleGrootte" : 246445.0,
      "perceelnummer" : 1102,
      "perceelnummerRotatie" : 0.0,
      "sectie" : "U",
      "soortGrootte" : null,
      "geometry" : {
        "type" : "Polygon",
        "coordinates" : [ [ [ 3.787065768861086, 51.32406722774413 ], [ 3.78723539221826, 

Nou moet het haast wel zo zijn dat ik iets vreselijk over het hoofd aan het zien ben, maar ik kan er maar niet achter komen. Iemand enig idee?

Content-Type: application/json; charset=utf-8

… is de boosdoener. Als je daar alles na application/json vanaf haalt, krijg je wel je verwachtte resultaat.

Dit is een bug in de API. Er staat een fix klaar die waarschijnlijk morgen doorgevoerd wordt. Hierna zou je huidige request (met ; charset=utf-8) ook moeten werken.

Dat is (helaas) een bug in het component dat het datamodel moet weergeven, voor de BAG en de BRT werkt het wel. We hebben deze scherp en gaan het binnenkort oplossen. Deze bug heeft verder nieuws te maken met de nieuwe API.

Inderdaad, de migratie is helaas niet helemaal vlekkeloos verlopen ondanks dat de nieuwe API specificatie wel backwards compatible is met de vorige. Toen die API gemaakt werd genereerden we de API nog niet op basis van de API specificatie en klaarblijkelijk vertelt de oude API specificatie niet goed genoeg hoe de oude API werkt. Onze excuses voor de overlast.

Okey, dank voor de hulp heren.
Dergelijke overgangsmomenten zijn altijd tricky.
Gelukkig staat ons systeem nu nog niet in productie.

De bug waar je gisteren tegen aan liep is verholpen.
Het (correcte) request dat je gisteren probeerde, komt er nu zonder problemen doorheen.

1 like

Beste Jasper,

Sinds vrijdag 20 juli krijgen we een 400 fout terug op de aanroep van percelen via https://brk.basisregistraties.overheid.nl/api/v1/perceel.

We doen een put request met deze body:
{
“kadastraleGemeentenaam”: null,
“kadastraleGemeentecode”: “RSN01”, // hier komt de geselecteerde kadastrale gemeentecode
“sectie”: “F”, // hier komt de ingevoerde sectie
“perceelnummer”: “4078” // hier komt het ingevoerde perceelnummer
}

We krijgen daar een 400 fout op.

Kun jij me vertellen wat er aan de hand is?

Groet,

Marjolein

Hallo Marjolein,

Als ik de open api spec erbij haal (https://brk.basisregistraties.overheid.nl/api/v1 ) en die in een swagger-editor stop (bijvoorbeeld online op https://editor.swagger.io/ ) dan wordt de specificatie afgebeeld met voorbeelden van ondersteunde verzoeken. Je kunt zelfs verzoeken daarmee testen.
Als ik kijk naar de put op /perceel, dan verwacht deze een geometrie
Dat is heel wat anders dan dat je in de body stopt.

Heeft het wel gewerkt?

Groet,

Koos

Beste Koos,

Dit heeft zo gewerkt. Tot ergens vorige week.
Is er vorige week wat in jullie api veranderd / kan dit met de api wijziging van 10 juli te maken hebben?

Groet,

Marjolein

Hoi Marjolein,

Het klinkt misschien raar, maar dat dit voorheen wél heeft gewerkt was een ‘bug’ die verholpen is in de nieuwe versie. De PUT request op /perceel is bedoeld voor zoeken op geometrie, niet voor filteren op andere properties. Mocht er de wens bestaan om te kunnen filteren op andere properties dan zullen we dit inventariseren en de beste manier om dat te bewerkstelligen meenemen in een nieuwe versie. Wat is jullie usecase precies?

Groet, Dimitri

Beste Dimitri,

Onze usecase is dat we kadastralegemeentecode, sectie en perceelnummer invoeren en de geometrie terugkrijgen.
Via welke API kan dat?

Groet,

Marjolein

Momenteel kan dat niet, dus dat lijkt me een goede feature request. Zoeken jullie echt op die afzonderlijke eigenschappen of op een samengesteld iets?

Hi Dimitri,

We zoeken op de samengestelde eigenschappen, dus altijd op gemeentecode, sectie en perceelnummer.
Zou erg fijn zijn als jullie dit kunnen realiseren.

Nog fijner zou zijn als jullie de “bugfix” terug kunnen draaien en de oude functionaliteit weer beschikbaar stellen totdat deze feature op een andere manier beschikbaar is. Onze klanten missen deze functionaliteit nu.

Groet,

Marjolein

We gaan er naar kijken.