Introductie

De ParkeerLUL API biedt programmeurs de mogelijkheid zelf applicaties te ontwikkelen met de data van ParkeerLUL.nl.

Momenteel mag een ieder tegen de REST API aan ouwehoeren, zonder vooraf toestemming te vragen. Aan de andere kant zien wij onszelf ook vrij om een ieder keihard te blokkeren als we misbruik zien.

URLs

Toegang tot de API gaat over HTTPS via https://api.parkeerlul.nl.

Endpoint Methode Functie
/v1/aangiftes GET Aangiftes zoeken
/v1/aangiftes POST Nieuwe aangifte
/v1/aangiftes/<aangifte_id> GET Aangifte informatie
/v1/autos/<kenteken> GET Auto merk
/v1/fotos POST Nieuwe foto
/v1/gebruikers GET Gebruikers zoeken
/v1/gebruikers/ik GET Gebruikers informatie (huidige gebruiker)
/v1/gebruikers/<gebruikersnaam> GET Gebruikers informatie

Response structuur

Elke response bestaat uit een JSON document met drie keys, status, message en data.

{
    "status": "success",
    "message": null,
    "data": {
        "avatar": "http://www.parkeerlul.nl/img/profile/1323.png",
        "username": "bob"
    }
}

Afhankelijk van de status (welke "success" of "error" kan zijn), bevat data of message informatie die nuttig zou kunnen zijn.

Limieten

Per uur mag elke applicatie 3600 requests maken, daarna zul je een HTTP status 429 - Too Many Requests ontvangen. Elke response geeft aan hoeveel requests je hebt gebruikt en hoeveel je er mag maken. Mocht je over de limiet gaan, dan geeft de header X-ParkeerLUL-API-Expire aan hoeveel seconden je moet wachten. Voorbeeld:

X-ParkeerLUL-API-Expire: 1733
X-ParkeerLUL-API-Limit: 3600
X-ParkeerLUL-API-Units: req/hour
X-ParkeerLUL-API-Used: 3600

Authenticatie

Authenticatie wordt verricht middels Basic Auth waarbij de gebruiker zijn gebruikersnaam en API sleutel opgeeft. Gebruikers kunnen inloggen via social media accounts (oauth) of via een gebruikersnaam en wachtwoord. Gezien niet elke gebruiker een wachtwoord heeft, is er een API sleutel beschikbaar gesteld die de gebruiker op elk moment veranderen kan. De API sleutel kan gevonden worden op de instellingen pagina op ParkeerLUL.nl.


Resources

Aangiftes

Aangiftes kunnen middels een GET doorzocht worden, en middels een POST request aangemaakt worden. Voordat je een nieuwe aangifte aanmaakt, zul je eerst een foto moeten uploaden (zie Foto's).

Een POST (nieuwe aangifte) vereist de volgende input:

  • date - datum in YYYY-MM-DD HH:MM:SS formaat (CEST)
  • foto_id - het foto id verkregen met foto upload
  • lat - latitude (floating point)
  • lon - longitude (floating point)
  • plate - kenteken

Een succesvolle aangifte resulteert in een 201 status, met een Location header, waar de aangifte gevonden kan worden.

Incorrecte of missende waarden geven een 400 status.


Auto's

Om te kijken of een kenteken bekend is, kun je het merk van de auto opvragen. Veel meer info dan 't merk zul je niet krijgen. Voorbeeld:

{
    "data": {
        "merk": "BMW"
    },
    "message": null,
    "status": "success"
}

Foto's

We proberen zoveel mogelijk informatie uit de geüploade foto's zelf te halen (denk aan GPS info, kenteken (middels OCR), en datum). Hierdoor is het van belang dat in de eerste stap van de aangifte, je een foto POST. Je krijgt dan een id terug met data wat gevonden is. Voorbeeld:

{
    "data": {
        "date": "2011-04-26 13:38:57",
        "foto_id": "1419772456.jpeg",
        "gps": {
            "lat": "52.36650888888889",
            "lon": "5.19095111111111"
        },
        "plates": [
            "71-PH-GD",
            "71-PH-SD",
            "71-PHG-0",
            "71-PH-CD",
            "71-PH-GO",
            "71-PH-GQ",
            "71-PH-GB",
            "71-PHS-0",
            "71-PH-50",
            "71-PH-60",
            "71-PH-SO",
            "71-PH-SQ",
            "71-PHC-0",
            "71-PH-SB"
        ]
    }, 
    "message": null, 
    "status": "success"
}

plates kan meerdere opties bevatten, zoals 't voorbeeld aangeeft, aangezien OCR niet perfect is en er meerdere auto's in de foto kunnen staan. Het is dus handig om de gehele lijst aan de client aan te bieden. De foto_id waarde dien je later met je aangifte moeten terugsturen.


Gebruikers

Gebruikers aanmaken kan alleen via de website. De gebruikers resource accepteert dan ook alleen GET requests om informatie over gebruikers op te halen.