Wednesday 17 December 2014

GBIF API's

Sinds het voorjaar van 2014 is de eerste officiĆ«le versie van de GBIF API's online. Deze API’s bieden iedereen de mogelijkheid om de GBIF databases te benaderen en naar wens informatie op te halen over een plant- of diersoort, een dataset, een land, en meer. Dit artikel laat kort zien welke technieken er gebruikt worden en hoe eenvoudig het, met een beetje programmeerkennis, kan zijn om de GBIF informatie voor eigen doeleinden op te halen, te gebruiken en te presenteren. In dit artikel geven we wat PHP programmeercode als voorbeeld voor het ophalen van de informatie. In de meeste andere programmeertalen zijn er vergelijkbare functies en scripts beschikbaar.

De GBIF API’s zijn te benaderen via een URL en geven dan (meestal) een JSON object terug met de informatie die je hebt opgevraagd. JSON (JavaScript Object Notation) is een manier om informatie uit te wisselen, die vergelijkbaar is met een vereenvoudigde versie van XML. Klik hier voor meer informatie.

Datasets met metadata
Als voorbeeld zullen we hier alle Nederlandse GBIF datasets met metadata ophalen.  De complete beschrijving van de dataset API is hier te vinden.

-----------------------------------------------------------------------------------
$URLGetDutchDatasets="http://api.gbif.org/v1/dataset/?country=nl&limit=200";
$datasetsJSON = file_get_contents($URLGetDutchDatasets);
$datasets = json_decode($datasetsJSON, true);

$numberOfDutchDatasets = $datasets['count'];

foreach($datasets['results'] as $dataset) {
     $organisationKey = $dataset['publishingOrganizationKey'];
     $datasetKey = $dataset['key'];
     $datasetNameInGbif = $dataset['title'];
     $datasetType = $dataset['type'];
     $datasetRegistrationDate = $dataset['created'];
     $datasetLastPublicationDate = $dataset['modified'];
}
-----------------------------------------------------------------------------------
De eerste PHP-regel beschrijft de URL van de query aan de dataset API. Met de country parameter kunnen we een land selecteren en de limit parameter geeft het aantal dataset-objecten, die de API maximaal terug zal geven. Een complete lijst met voorbeeld parameters is hier te vinden. Je kan de GetDutchDatasets URL overigens ook gewoon in de browser invoeren om wat gevoel te krijgen welke informatie er wordt teruggeven door de API. Je kan zo ook snel zien hoe een JSON object eruitziet.

De tweede en derde regel halen respectievelijk de informatie op van de API en zetten het JSON object om in een associative array. De vierde regel leest het veld count, het aantal (Nederlandse) datasets in de query, uit de associative array. Dit aantal is onafhankelijk van de limit-parameter, dus met limit=10 zal de count waarde gewoon 124 zijn. De waarde datasets bevat een verzameling met objecten van datasets met de metadata van de individuele datasets. In de foreach-loop worden wat velden van een dataset uitgelezen.

Statistieken van een dataset
De occurrence API kan onder andere gebruikt worden om de primaire data van een individueel record op te halen, maar ook voor het uitlezen van metrics van een dataset. Hieronder een voorbeeld van het uitlezen van het aantal records van een dataset.

-----------------------------------------------------------------------------------
$URLgetRecordCountOfDataset = "http://api.gbif.org/v1/occurrence/count?datasetKey=740df67d-5663-41a2-9d12-33ec33876c47";
$recordCount = file_get_contents($URLgetRecordCountOfDataset);
-----------------------------------------------------------------------------------

Zoals je wellicht is opgevallen wordt hier de output van de API niet meer omgezet van een JSON object naar een array. GBIF geeft bij deze specifieke count functie alleen een nummer terug van het aantal records, zonder het JSON format. Er is immers maar een waarde, dus het JSON formaat zou onnodige overhead geven. De variabele $recordCount bevat dus direct de waarde van het aantal records van de dataset. GBIF biedt met parameters als isGeoreferenced en basisOfRecord mogelijkheden om meer verdieping in dit enkele nummer te brengen, zie hier voor meer informatie.


No comments:

Post a Comment