Verkeersborden beheer API 5.0
API beschrijving
Met de beheer API voeg je verkeersborden toe aan George en wijzig je ze, zonder de George-applicatie te gebruiken. De API is bedoeld voor assetmanagementsystemen die George automatisch willen bijwerken.
Wil je alleen verkeersborden ophalen? Gebruik dan de Verkeersborden download API 5.0. Wil je veel borden tegelijk wijzigen met een bestand? Zie dan Bulkupload.
De API-specificatie staat op de pagina Swagger UI Verkeersborden beheer API 5.0.
Toegang
Voor het aanleveren heb je een toegangstoken nodig. Je krijgt dit van de NDW authenticatieserver (https://iam.ndw.nu/auth/realms/ndw/protocol/openid-connect/token). Het token moet de rol traffic_sign_api hebben.
Vraag via de NDW Servicedesk een account aan voor je systeem. Een systeem gebruikt de OAuth2 client credentials flow.
Het ophalen van één verkeersbord (GET .../main-signs/{id}) heeft geen token nodig.
Services
Alle services staan onder https://data.ndw.nu/api/rest/static-road-data/traffic-signs/v5/main-signs.
| Methode | Pad | Beschrijving |
|---|---|---|
| POST | /main-signs |
Maak een nieuw verkeersbord aan |
| PUT | /main-signs/{id} |
Wijzig een bestaand verkeersbord |
| POST | /main-signs/test |
Controleer een nieuw verkeersbord zonder het op te slaan |
| PUT | /main-signs/{id}/test |
Controleer een wijziging zonder die op te slaan |
| GET | /main-signs/{id} |
Haal één verkeersbord op zoals het nu is opgeslagen |
Verkeersborden aanleveren
Je levert een verkeersbord aan als GeoJSON Feature, met type, geometry en properties. Binnen properties zijn alleen rvvCode, placement en bearing verplicht. Zonder deze velden kan George het bord niet plaatsen.
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [5.94342, 50.92481]
},
"properties": {
"rvvCode": "A1",
"blackCode": "50",
"placement": "ALONG",
"bearing": 49,
"supplementarySigns": [
{ "signCode": "OB401", "text": "150 m" }
],
"externalReferences": [
{ "system": "mijn-assetsysteem", "id": "TS123456" }
]
}
}
Bij een nieuw bord laat je id weg. George kent die toe.
In rvvCode mag je ook een IMBOR-code aanleveren. Welke IMBOR-codes George accepteert en waar George ze naar omzet, staat op de pagina IMBOR-codes.
De coördinaten zijn standaard WGS84. Gebruik je Rijksdriehoek? Zet dan de header Content-Crs op http://www.opengis.net/def/crs/EPSG/9.9.1/28992.
In de Swagger UI staat bij elke eigenschap met één woord wat George ermee doet:
- Required: Verplicht.
- Accepted and used: George bewaart wat je aanlevert.
- Accepted and ignored: George bepaalt deze waarde zelf. Wat je aanlevert, wordt niet opgeslagen. Zo kun je een bord dat je uit George hebt opgehaald ongewijzigd terugsturen.
De aangeleverde borden worden gecontroleerd volgens dezelfde regels als bij de handmatige invoer van verkeersborden in George, zie daarvoor de handleiding van George.
Onderborden
Een hoofdbord kan meerdere onderborden hebben. Je levert ze allemaal in één POST of PUT aan.
Met index geef je de groep aan waar een onderbord bij hoort. Onderborden die samen op één bordje onder het hoofdbord staan, vormen een groep en krijgen dezelfde index. Groep 0 hangt direct onder het hoofdbord, elke volgende groep krijgt een index die één hoger is. Zet de onderborden op volgorde van index en sla geen groep over: 0, 0, 1, 2 is goed, 0, 2 of 1, 0 niet. Anders wordt het bord afgewezen. Zonder index geldt 0.
Gecombineerde onderborden
Staan er meerdere symbolen op één onderbord, dan kun je dat onderbord aanleveren met één gecombineerde signCode. Zet de onderbordcodes achter elkaar, eventueel gescheiden door een underscore, bijvoorbeeld OB503_OB02 of OB503OB02. Elke code begint met OB. George maakt van elke code een apart onderbord, allemaal met de index van het onderbord dat je hebt aangeleverd. Ze blijven dus samen in één groep.
Dit aanleveren:
"supplementarySigns": [
{ "signCode": "OB503_OB02", "index": 0 },
{ "signCode": "OB401", "text": "150 m", "index": 1 }
]
levert deze onderborden op:
"supplementarySigns": [
{ "signCode": "OB503", "index": 0 },
{ "signCode": "OB02", "index": 0 },
{ "signCode": "OB401", "text": "150 m", "index": 1 }
]
Hetzelfde resultaat krijg je door de codes als losse onderborden met dezelfde index aan te leveren. Dat is nodig als meerdere delen een eigen tekst hebben: een text bij een gecombineerde signCode geldt voor elke code in die combinatie waar tekst op hoort.
Een f achter een code (fluorescerend) mag, maar wordt niet opgeslagen. Je mag ook IMBOR-onderbordcodes gebruiken. George zet die om naar zijn eigen onderbordcodes. Welke dat zijn, staat op de pagina IMBOR-codes.
Onderborden in de RVV-code
Je kunt onderbordcodes ook achter de RVV-code in rvvCode zetten, bijvoorbeeld A1_OB501l. Deze onderborden komen bovenaan, met index 0. De index van de onderborden uit supplementarySigns schuift dan één op. Dit kan niet bij een gecombineerde IMBOR-code.
Tekst op een onderbord
Geef text alleen mee bij een onderbord waar tekst op staat, zoals OB401. Komt de tekst niet terug in een van de onderborden die George uit de signCode maakt, dan voegt George een extra onderbord van het type OTHER met die tekst toe.
Verwerking
De verwerking is asynchroon. Een succesvolle response betekent dus niet dat het bord al helemaal is verwerkt.
In de response bevat comments de opmerkingen die je zelf hebt aangeleverd, gevolgd door de meldingen van George. Dat kan een fout zijn waardoor het bord is afgewezen, maar ook een waarschuwing bij een bord dat wel is geaccepteerd, bijvoorbeeld als een aangeleverde blackCode wordt genegeerd omdat de IMBOR-code al een blackCode bepaalt. Vergelijk comments in de response daarom met wat je hebt aangeleverd.
POST: nieuw bord aanmaken. Met een POST maak je een nieuw verkeersbord aan. Een gecombineerde IMBOR-code splitst George in twee borden. Dit zijn de IMBOR-codes A0130E01zb, A0130E01zbh (A1 en E1) en A0230-E01ze (A2 en E1). Eén POST kan dus meerdere borden opleveren. Een combinatie van RVV-codes, zoals A1E1, is geen geldige code en wordt afgewezen. Je krijgt status 202 Accepted als minstens één bord in behandeling is genomen. De body bevat elk bord zoals je het hebt aangeleverd, aangevuld met de id die George heeft toegekend. Een POST kan geaccepteerde en afgewezen borden bevatten. Een afgewezen bord heeft geen id en een uitleg in comments. Controleer daarom elk bord in de response op een id en vertrouw niet alleen op de statuscode.
PUT: bestaand bord wijzigen. Met een PUT wijzig je één bestaand verkeersbord. Een gecombineerde code wordt bij een PUT niet geaccepteerd en geeft een 400. Zo'n code staat in George voor twee aparte verkeersborden, elk met een eigen id. Wijzig die borden daarom met twee aparte PUT-verzoeken. Een id in de body moet gelijk zijn aan de id in het pad, anders krijg je een 400. Een id in het pad dat geen geldige UUID is, geeft ook een 400. Verder krijg je altijd status 202 Accepted, ook bij een afgewezen bord of een id dat niet bestaat. Bij een onbekend id staat in comments dan "Onbekend verkeersbord". Je krijgt hier geen 404. De body bevat het bord zoals je het hebt aangeleverd, met de id uit het pad. Omdat de response dus altijd een id heeft, kijk je naar comments: heeft George daar niets aan toegevoegd, dan is de wijziging in behandeling genomen.
De body van de response is niet het opgeslagen bord. Wat George zelf afleidt, zoals de gemeente, ontbreekt hier nog. Haal het bord daarna op met GET /main-signs/{id} om te zien wat er is opgeslagen. Omdat de verwerking even duurt, kan deze GET direct na het aanleveren nog een 404 of de oude gegevens geven. Haal je het bord automatisch op, wacht dan even of probeer het opnieuw.
Eerst testen
Met de test-services valideert George je bericht op dezelfde manier als bij het echt aanleveren, maar slaat niets op. Heeft George niets aan comments toegevoegd, dan zou het bord worden geaccepteerd. Bij een test-POST krijgt geen enkel bord een id.
Responses
| Status | Betekenis |
|---|---|
| 200 | Alleen bij de test-services en bij het ophalen van één bord |
| 202 | POST: minstens één bord is in behandeling genomen. PUT: altijd, controleer wat George aan comments heeft toegevoegd |
| 400 | Het bericht is ongeldig (application/problem+json), of bij een POST kon geen enkel bord worden verwerkt (application/json, met uitleg in comments). Ook bij een PUT met een gecombineerde code, een id in de body dat afwijkt van het pad of een id in het pad dat geen geldige UUID is |
| 401 | Er is geen geldig toegangstoken meegestuurd |
| 403 | Het toegangstoken heeft niet de rol traffic_sign_api |
| 404 | Alleen bij het ophalen van één bord: het bord bestaat niet. Een PUT op een onbekend id geeft geen 404, maar een 202 met "Onbekend verkeersbord" in comments |
Als je vragen hebt over deze API, neem dan contact op met de NDW Servicedesk.
Ga terug naar de vorige pagina