NL:Taginfo/API

Taginfo heeft een API die u op verscheidene manieren toegang verschaft tot de inhoud van zijn database. De API wordt intern gebruikt voor de webgebruiker interface en kan ook wordne gebruikt door iedereen die gegevens van Taginfo wil integreren in zijn websites of toepassingen.

De server die de API voor Taginfo uitvoert heeft geen onbeperkte mogelijkheden. Gebruik de API met beleid. maak geen enorme aantallen verzoeken om de gehele database te verkrijgen of grote stukken ervan, gebruik in plaats daarvan de aangeboden database downloads.

Als u de API van Taginfo gebruikt wordt aanbevolen dat zich abonneert op de taginfo-dev mailinglijst. Bijwerken van de API zal daar worden aangekondigd en het is ook de juiste plaats voor al uw vragen.

Basis

De API is een RESTful HTTP API. Alle verzoeken worden gedaan door URL's beginnend met http://taginfo.openstreetmap.org/api/VERSION . API Versie 4 is de huidige.

Alle aanroepen van de API zijn alleen-lezen en gebruiken het HTTP GET-verzoek, alle parameters worden zoals gewoonlijk op0gegeven in de URL.

Alle resultaten van de API zijn in de indeling JSON (met uitzondering van een aantal aanroepen die een PNG teruggeven).

Paginering

Vele aanroepen van de API geven hun gegevens "pagina per pagina" terug, dus u kunt, zeg, de eerste 20 resultaten in één verzoek krijgen, dan de volgende 20 enzovoort. U kunt zelf bepalen hoeveel resultaten u wilt en welke "pagina" of u kunt gewoon alles in één keer krijgen.

Voeg de parameters page en rp (resultaten per pagina) toe aan de URL indien u wilt pagineren. De eerste pagina heeft nummer 1. Dus zal de URL er uitzien als

http://taginfo.openstreetmap.org/api/VERSION/some/thing?rp=20&page=1&foo=bar

De resultaten van de aanroep van de API zullen er uitzien als:

{
  "total": 587,   // het totale aantal resultaten
  "page":  7,     // het paginanummer (hetzelfde als in uw verzoek)
  "rp":    20,    // het aantal resultaten per pagina (hetzelfde als in uw verzoek)
  "url":   "http://taginfo.openstreetmap.org/api..."  // de volledige gebruikte URL om dit resultaat te verkrijgen
  "data":  [...]  // de gegevens
}

De array data zal de actuele resultaten bevatten van item rp * (page-1) tot en met rp * page - 1.

Als u geen paginering wilt, voeg dan de page en rp niet toe, in de resultaten zullen deze velden dan 0 zijn.

Sorteren

Veel aanroepen van de API ondersteunen het sorteren van de resultaten. U kunt de parameters sortname en sortorder aan de URL toevoegen om een ander resultaat te krijgen dan de standaard sortering. Elk verzoek aan de API heeft verschillende opties voor sortname. De sorteervolgorde kan zijn asc voor oplopend of desc voor aflopend.

Filters

Sommige aanroepen van de API hebben een speciale parameter filter die u in staat stellen de resultaten te filteren. U kunt meerdere filters gebruiken, op deze manier: filter=FILTER1,FILTER2.

bekijk de beschrijvingen voor "Filter" in de API Documentation voor informatie over welke aanroepen welke filters hebben.

Voorbeeldcode

Het eenvoudige programma tapi (https://github.com/joto/taginfo/blob/master/examples/tapi) kan worden gebruikt om verzoeken voor de API te maken en zou kunnen helpen bij het ontwikkelen van uw eigen toegangscode voor de API.

Aanroepen van de API

In het algemeen gesproken is er een aanroep van de API voor elke tabel in de webgebruikersinterface (dat komt omdat die tabellen worden gevuld vanuit de aanroepen van de API). Soms geven de aanroepen van de API meer velden met gegevens terug dan wordt weergegeven in de gebruikersinterface.

Zie http://taginfo.openstreetmap.org/taginfo/apidoc voor een lijst met aanroepen van de API.

XSS problemen

Onthoud dat tagsleutels en waarden van OSM elk geldig teken in UTF-8 kunnen bevatten, net als pagina's van een wiki. Wanneer u de API van Taginfo gebruikt is er altijd een kans dat het gegevens teruggeeft die speciale tekens bevatten. Zorg er in uw toepassingen voor dat deze tekens correct worden afgehandeld.

Pretty JSON

U kunt de parameter format=json_pretty toevoegen om pretty-printed JSON-uitvoer te verkrijgen met spaties en nieuwe regels. De standaard is om de JSON zo dicht mogelijk te verpakken.

CORS en JSONP

Taginfo ondersteunt Cross-Origin Resource Sharing (CORS) foor het instellen van de kop Access-Control-Allow-Origin: * op alle resultaten van de aanroep van de API. Dit is de geprefereerde methode van het gebruik van de API van Taginfo vanaf andere webpagina's.

Taginfo ondersteunt ook de oudere techniek JSONP. U kunt de parameter callback toevoegen aan elke aanroep van de API die JSON teruggeeft en het zal de resultaten weergeven, verpakt in een functie-aanroep naar de parameter callback.

Voorbeeld: ...&callback=foo

zal teruggeven foo(...enige JSON...).