Handleiding voor implementatie WEBSERVICE GEOCODEREN

Transcriptie

1 Handleiding voor implementatie WEBSERVICE GEOCODEREN Opgesteld door Bridgis BV Datum 13 september 2012

2 INHOUDSOPGAVE 1 Geocoderen 3 2 Bridgis Adreslocaties 3 3 URL 3 4 Functie 3 5 Input en Output Parameters Resultaat 6 6 Foutmeldingen 7 7 Servicedesk 8 Over Bridgis 8 2

3 1 GEOCODEREN Geocoderen is één van de services uit de productrange Geo-webservices. Met (online) Geocoderen kunt u snel én eenvoudig objecten tot op gebouwniveau voorzien van de juiste coördinaten. De service geeft coördinaten bij een adres of postcode (geen postbussen). Deze kunnen worden opgevraagd in zowel WGS84/LatLong als in het Rijksdriehoekstelsel. 2 BRIDGIS ADRESLOCATIES Geocoderen maakt gebruik van Bridgis Adreslocaties. Dit is het enige volledig landsdekkende adrescoördinatenbestand in Nederland. Alle bestaande adressen (postcode, huisnummer en toevoeging) zijn op peildatum opgenomen en voorzien van een nauwkeurige xy-coördinaat. Van ca. 98,5% van alle adressen ligt de coördinaat in een TOP10-vectorbouwvlak. Naast coördinaten op adresniveau gebruikt de service coördinaten (centroïden) van postcodegebieden. 3 URL Geocoderen is te bereiken via U komt hiermee op een pagina waar u de werking kunt testen. Let op: testaanroepen die hier worden gedaan wordt in mindering gebracht op uw tegoed aan credits indien het coördinaat wordt gevonden. Ook vindt u op deze pagina een verwijzing naar het SOAP protocol. De WSDL kan worden opgevraagd via 4 FUNCTIE biedt de volgende functies: AdresCoord: De desbetreffende geocodeerservice. Deze geeft een coördinaat voor een adres of postcode met een in te stellen XY nauwkeurigheid. AdresCoord2: De desbetreffende geocodeerservice. Deze geeft een coördinaat voor een adres of postcode met een in te stellen match nauwkeurigheid. KwaliteitCoordinaat: Deze functie geeft een lijst van de mogelijke kwaliteiten van coördinaten met een uitleg per kwaliteit. Dit betreft een kwaliteitsaanduiding m.b.t. hoe Bridgis het adres heeft kunnen vinden in de service op basis van uw invoer. XYQualityCoordinate: Deze functie geeft een lijst van de mogelijke kwaliteiten van coördinaten met een uitleg per kwaliteit. Dit betreft een kwaliteitsaanduiding m.b.t. hoe Bridgis in de brondata de xy-coördinaat van een adres (Bridgis Adreslocaties ) heeft kunnen bepalen. 3

4 5 INPUT EN OUTPUT 5.1 PARAMETERS Voor het verkrijgen van de gewenste resultaten gelden een aantal input parameters. Hieronder ziet u een overzicht van de parameters, gevolgd door een toelichting. NAAM TYPE BESCHRIJVING suser String Gebruikersnaam spassword String Wachtwoord emaxgewenstexykwaliteit String Geocoderen tot gewenste kwaliteit van het xycoördinaat emaxgewenstematchkwaliteit String Matchen tot en met bepaald niveau coordinatetype String Keuze coördinatenstelsel swoonplaats String Woonplaats sstraatnaam String Straatnaam spc6 String 6-positie postcode ihuisnummer Integer Huisnummer stoevoeging String Toevoeging Een adres bestaat uit een combinatie van ten minste: - swoonplaats, sstraatnaam, ihuisnummer, optioneel stoevoeging - spc6, ihuisnummer, optioneel stoevoeging suser en spassword De gebruikersnaam en wachtwoord die u heeft ontvangen van Bridgis voor het gebruik van Geo-webservices. Het betreft verplichte invoervelden. Let op deze velden zijn hoofdlettergevoelig. 4

5 emaxgewenstematchkwaliteit Met deze parameter kunt u aangeven wat de minimale kwaliteit van de match met de gevonden coördinaat mag zijn. De onderstaande kwaliteiten zijn beschikbaar: 1. [PHT]: Postcode, huisnummer toevoeging 2. [WSHT]: Straatnaam, plaatsnaam-nen, huisnummer, toevoeging 3. [W2S3HT]: Straatnaam, plaatsnaam-nonnen, huisnummer, toevoeging 4. [PH]: Postcode, huisnummer 5. [WSH]: Straatnaam, huisnummer, woonplaats-nen 6. [W2S3H]: Straatnaam, huisnummer, woonplaats-nonnen 7. [PC6]: 6-positie postcode 8. [PC5]: 5-positie postcode 9. [PC4]: 4-positie postcode De service zal altijd proberen zo nauwkeurig mogelijk te geocoderen. Het resultaat wordt bepaald door enerzijds de volledigheid en juistheid van uw gegevens, en anderzijds de 'match' van deze gegevens met de gebruikte bestanden. emaxgewenstexykwaliteit Met deze parameter kunt u aangeven wat de minimale kwaliteit van de coördinaat mag zijn. De onderstaande kwaliteiten zijn beschikbaar: 1. [1]: Point-in-polygon. De broncoördinaten van het adres liggen in het bouwvlak. 2. [2]: Buffer of projectie. De broncoördinaten van het adres vallen buiten het bouwvlak. Het adres is via diverse algoritmen aan het meest waarschijnlijke bouwvlak toegekend. 3. [3]: Tijdelijk bouwvlak. Er zijn coördinaten berekend op basis van een kunstmatig gecreëerd bouwvlak, omdat van het adres wel broncoördinaten bekend zijn, maar er (nog) geen bouwvlak op de topografische kaart bestaat. 4. [4]: Logische toe- of tussenvoeging. Er bestaan geen broncoördinaten, maar het adres maakt wel deel uit van een (bestaande) reeks waaraan het wordt toegevoegd. 5. [5]: Gegeocodeerd op 6-positie postcode. Er bestaan geen broncoördinaten en het adres maakt geen deel uit van een logische reeks, maar er bestaat wel een 6-positie Postcodelocatie waaraan het adres wordt toegekend. 6. [6]: Gegeocodeerd op Straatlocatie. Er bestaan geen broncoördinaten en het adres maakt geen deel uit van een logische reeks of 6-positie Postcode, maar er bestaat wel een Straatlocatie waaraan het adres wordt toegekend. 7. [7]: Gegeocodeerd op 5-positie postcode. Er bestaan geen broncoördinaten en het adres maakt geen deel uit van een logische reeks of straat, maar er bestaat wel een 5-positie Postcodelocatie waaraan het adres wordt toegekend. 8. [8]: Gegeocodeerd op 4-positie postcode. Er bestaan geen broncoördinaten en het adres maakt geen deel uit van een logische reeks, straat of 5-positie postcode, maar er bestaat wel een 4-positie Postcodelocatie waaraan het adres wordt toegekend. De kwaliteiten 1 t/m 4 zijn door Bridgis tevens verlegd naar de bijbehorende weg. Vanaf kwaliteit 5 is het coördinaat niet meer op adresniveau en daarom is het vanaf deze kwaliteit niet op de weg beschikbaar. coordinatetype Deze parameter beschrijft het coördinatenstelsel waarin de coördinaten worden opgevraagd. Het te gebruiken coördinatenstelsel kan als volgt worden opgegeven: 5

6 - Rijksdriehoekstelsel: [RD] - WGS84LatLong: [WGS84] (te gebruiken voor projectie op bijvoorbeeld Google maps). - Rijksdriehoekstelsel maar coördinaten verplaatst naar de bijbehorende straat in plaats van in een bouwvlak: [STREET] (STREET-coördinaten zijn beschikbaar t/m kwaliteit 4, bij een lagere kwaliteit krijgt u wel respons dit is dan echter een [RD] coördinaat. Er dient altijd een keuze gemaakt te worden. swoonplaats Deze parameter beschrijft de woonplaats. sstraatnaam Deze parameter beschrijft de straatnaam. spc6 Deze invoerparameter geeft de 6-positie postcode weer. De notatie is als volgt: 1234AA, 1234A of 1234, afhankelijk van de gewenste kwaliteit. ihuisnummer Deze invoerparameter geeft het huisnummer weer. Dit mag een 0 of negatieve waarde zijn (bijv. bij het opvragen van een postcodecoördinaat). stoevoeging Deze invoerparameter geeft de toevoeging van het huisnummer weer en is altijd optioneel. 5.2 RESULTAAT Als output wordt de onderstaande informatie teruggeleverd. NAAM fx float fy float ematchq int BESCHRIJVING [RD] X van de coördinaat of 0 indien eq=0 of negatief is [WGS84] Longitude van de coördinaat of 0 indien eq=0 of negatief is [RD] Y van de coördinaat of 0 indien eq=0 of negatief is [WGS84] Latitude van de coördinaat of 0 indien eq=0 of negatief is Kwaliteit van de match in onze database. De onderstaande kwaliteiten zijn mogelijk (een beschrijving is ook te bekijken via de functie KwaliteitCoordinaat) 1 PHT: Postcode, huisnummer toevoeging 2 WSHT: Straatnaam, plaatsnaam, huisnummer, toevoeging 3 W2S3HT: Straatnaam, plaatsnaam-nonnen, huisnummer, toevoeging 4 PH: Postcode, huisnummer 5 WSH: Straatnaam, huisnummer, woonplaats 6

7 6 W2S3H: Straatnaam, huisnummer, woonplaats-nonnen 7 PC6: 6-positie postcode 8 PC5: 5-positie postcode 9 PC4: 4-positie postcode -3 OUTSIDE: Oorspronkelijke coördiaat ligt buiten bouwvlak -2 NOPOINT: Coördinaat niet gevonden -1 NOADDRESS: Adres en coördinaat niet gevonden 0 NOTHING: Error in invoer of tijdens uitvoering Voorbeeld: 6 FOUTMELDINGEN Foutmeldingen in onderstaande tabel worden teruggegeven via een SOAP-exception FOUTMELDING onbekende gebruiker OMSCHRIJVING De gebruikerscode (suser) is niet bekend (onjuist ingevoerd) Ongeldige postcode Toevoeging bevat enkele quotes Woonplaats te lang Straatnaam te lang Toevoeging te lang Onvoldoende bruikbare invoer Negatief huisnummer A general Exception De postcode (spc6) is niet in het juiste formaat gegeven. Postcodes moeten worden ingevoerd zonder spaties. Deze komt alleen voor als de postcode ook echt nodig is. Dit is het geval bij geocoderen tot kwaliteit WSH. De toevoeging bevat een apostrof (single quote) terwijl een toevoeging geen apostrof mag bevatten. De invoer is te lang. swoonplaats mag maximaal 43 tekens lang zijn. De invoer is te lang. swoonplaats mag maximaal 43 tekens lang zijn. De invoer is te lang. swoonplaats mag maximaal 6 tekens lang zijn. Er is geen volledige invoercombinatie gegeven voor een adres. De eisen voor de invoer zijn beschreven in paragraaf 5.1. Treedt alleen op als het huisnummer specifiek vereist is. Dit is het geval bij geocoderen tot emaxgewenstekwaliteit WSH. Een huisnummer moet in dit geval groter dan 0 zijn. Een Algemene of General exception kan optreden. In dit geval doet 7

8 has been thrown zich een probleem op de server voor zoals bijvoorbeeld een TimeOut of database access probleem. Wij adviseren u bij een dergelijke melding een ogenblik te wachten en de request na een aantal minuten nogmaals te herhalen. Indien de General exception blijft optreden, stop dan de verwerking en maak een melding via de Bridgis servicedesk, inclusief het tijdstip waarop de General exception is opgetreden. 7 SERVICEDESK Voor het melden van incidenten en calamiteiten kunt u contact opnemen met de Servicedesk: via helpdesk@bridgis.nl De condities zijn vermeld in de Service Level Agreement die hoort bij uw gebruikersovereenkomst. OVER BRIDGIS Bridgis maakt data en informatie geografisch toegankelijk. Wij integreren geografische databestanden van gerenommeerde datapartners in ons data-lab en maken deze toegankelijk via doelgroep- en toepassingsgerichte portalen. Neem voor meer informatie een kijkje op onze website via 8