Een tijdje geleden schreef ik een script om data te verkrijgen van de Mapillary API v3 en dat was vrij eenvoudig te gebruiken. Maar ondertussen is v3 van hun API uit gebruik genomen en moest ik dus mijn script herschrijven om v4 van de API te gebruiken. Het heeft me wel wat moeite gekost om uit te vissen hoe ik kon communiceren met de v4 API met behulp van Python.
Hieronder vind je een eenvoudig voorbeeld van hoe je info kan verkrijgen over de beelden die in de buurt van een bepaalde lengte- en breedtegraad liggen. Je kan dit concept uiteraard uitbreiden naar een veel uitgebreider script waarmee je bijvoorbeeld info verkrijgt over meerdere punten die opgeslagen wordt in een database. Maar voor dit voorbeeld vraag ik slechts de info op over beelden in de buurt van één set coördinaten. En daarna wordt die info weergegeven.
Een Client Token verkrijgen van Mapillary
Als je data wil verkrijgen uit de Mapillary API v4 heb je een “Client Token” nodig. Als je een oudere versie van de API gebruikte, moet je een nieuwe applicatie registreren, omdat de v3 tokens niet geldig zijn in de v4 API.
Om een Client Token te verkrijgen moet je een applicatie registreren op https://www.mapillary.com/dashboard/developers. Op die pagina vind je een knop om je applicatie te registreren. Als je daarop klikt, opent er een formulier dat redelijk zelfverklarend is. Alleen het veld “Callback URL” heeft iets meer uitleg nodig. Voor ons Python script is die instelling niet van belang, maar het is een verplicht veld dus je moet er iets voor invullen. Je kan er om het even welke url ingeven, maar als je informatie wil halen uit het resultaat van de Authentication URL, kan je bijvoorbeeld een PHP bestandje op een webserver zetten met onderstaande inhoud en de url naar dat bestandje zet je dan in het veld Callback URL.
<pre><?php print_r($_REQUEST); ?></pre>
callback.php
Je applicatie moet voor dit voorbeeld alleen toestemming hebben om te lezen, maar je kan ook scripts maken die kunnen schrijven of uploaden naar de Mapillary database.
Als je je applicatie geregistreerd hebt, kan je de Client Token vinden op de Developers Pagina op de Mapillary website: https://www.mapillary.com/dashboard/developers.
Je Client Token zal min of meer lijken op dit voorbeeld: MLY|52245453646433553|56cfcfab8eaf2cd3af2a51651879b23d
Let er wel op dat je je eigen gegenereerde Client Token gebruikt, want de token hierboven is een fictief voorbeeld die niet zal werken.
Voorbeeld Python script
In het script zijn er paar zaken die wat meer uitleg verdienen, daarom zal ik eerst de onderwerpen bounding box, headers en JSON resultaten bespreken en daarna het algemeen principe van het script verduidelijken en tot slotte krijg je het volledige voorbeeld script.
Bounding box
In dit voorbeeld vragen we informatie op van beelden die dicht bij een voorbeeldpunt gelegen zijn. Standaard is er in v4 van de API geen “CloseBy” bevraging meer mogelijk. In plaats daarvan kan je data opvragen over beelden binnen een “bounding box”. een bounding box is niet meer dan een noord georiënteerde rechthoek op de kaart. Om een bounding box te definiëren heb je 4 gegevens nodig:
- Minimum longitude (lengtegraad)
- Minimum latitude (breedtegraad)
- Maximum longitude
- Maximum latitude
Om in het voorbeeld deze bounding box te “maken”, neem ik het testpunt en voeg aan de coördinaten een bepaalde waarde toe of trek die waarde er van af. Op die manier krijg ik de vier waarden die de bounding box bepalen. In het voorbeeld gebruik ik de variabelen x_dist en y_dist als de waarden die bijgeteld of afgetrokken moeten worden. Ik heb beide variabelen op 0.00025° gezet, maar dit kan je aanpassen naar je eigen noden. Eén ding om in het achterhoofd te houden, is dat de API info over maximaal 2000 punten in je bounding box als resultaat geeft. Dus als je bounding box te groot is, zal je niet alle beschikbare data krijgen.
Headers
Dit is het onderdeel waarmee ik de meeste moeite had om juist te krijgen. Dat was vooral omdat ik op basis van de API documentatie (https://www.mapillary.com/developer/api-documentation/) alles veel moeilijker maakte dan nodig was. Dat resulteerde in een massa “500” foutmeldingen, omdat ik mijn bevragingen niet geauthenticeerd kreeg. Maar eigenlijk is de correcte manier om dat te doen heel eenvoudig, want je moet alleen de header waarde “Authorization” op “OAuth MLY|52245453646433553|56cfcfab8eaf2cd3af2a51651879b23d“ instellen. Natuurlijk moet je je eigen Client Token gebruiken en niet de voorbeeld token. Het stuk over de “OAuth 2.0” workflow in de officiële documentatie heb je niet nodig.
JSON resultaten
De API zal als resultaat van je bevraging een JSON bestand genereren. In dit voorbeeld zet ik die JSON om naar een dict met behulp van json(). Dat maakt het eenvoudig om de resultaten één voor één te overlopen.
Het algemene principe van het script
Het eerste wat het script doet, is alle afbeelding id’s (image_id) te verzamelen die zich binnen je bounding box bevinden met behulp van de https://graph.mapillary.com/images endpoint. Daarna overloopt het script elk van die afbeelding id’s en vraagt per id meer gedetailleerde info op met behulp van de https://graph.mapillary.com/{IMAGE_ID} endpoint. Voor dit tweede deel kan je zelf bepalen welke velden er opgevraagd moeten worden uit de Mapillary database. In het voorbeeld vraag ik de velden id, thumb_2048_url, captured_at en sequence op. Een beschrijving van alle beschikbare velden is te vinden op https://www.mapillary.com/developer/api-documentation#image.
Het script
import requests
metadata_endpoint = "https://graph.mapillary.com"
x_dist = 0.00025
y_dist = 0.00025
testpoint=[51.1543669,4.4436676]
client_token = 'MLY|4324601697617554|77cecffb3eef9cb3ff0a11471873f03c'
headers= { "Authorization" : "OAuth {}".format(client_token) }
# DOCS: https://www.mapillary.com/developer/api-documentation/#image (see "Image search")
url_imagesearch = metadata_endpoint+'/images?fields=id&bbox= {},{},{},{}'.format(testpoint[1]-x_dist, testpoint[0]-y_dist, testpoint[1]+x_dist, testpoint[0]+y_dist)
response_imagesearch = requests.get(url_imagesearch, headers=headers)
data_imagesearch = response_imagesearch.json()
print("Images found:" + str(len(data_imagesearch['data'])))
for image in data_imagesearch['data']:
# DOCS: https://www.mapillary.com/developer/api-documentation/#image
url_image = metadata_endpoint+'/{}?fields=id,thumb_2048_url,captured_at,sequence'.format(image['id'])
response_image = requests.get(url_image, headers=headers)
data_image = response_image.json()
print(data_image)test.py