# Hoe vind je OV-haltes in de buurt met een API?

> Ontdek hoe je met de ROOTE API haltes in de buurt zoekt: coördinaten, straal, JavaScript voorbeeld, resultaten lezen en fouten afhandelen.

Source: https://www.roote.ai/nl/guides/hoe-vind-je-ov-haltes-in-de-buurt-met-een-api/
Language: nl
Author: ROOTE

Om haltes rond een punt te zoeken, stuur je de latitude, longitude en een straal naar een nabijheid API. Controleer daarna de responsstatus, de teruggegeven entiteiten en de dekkingsinformatie voordat je de lijst of kaart toont.

In het ROOTE contract roote-1.0.0, opent de GET /v1/transit/nearby route de plekken voor openbaar vervoer in de buurt. Hij haalt geen vertrek- of realtime waarschuwingen op. Het zoeken van een plek en het opvragen van het volgende vertrek zijn twee aparte operaties.

## Parameters instellen

De request gebruikt lat voor latitude en lng voor longitude. De alias lon wordt ook in het contract beschreven. De radius parameter geeft de straal in meters aan; limit begrenst het aantal gevraagde resultaten. De filter modes kan de vervoerswijzen specificeren.

| Parameter | Voorbeeld | Betekenis |
| --- | --- | --- |
| lat | 44.8378 | Latitude van het zoekpunt |
| lng | -0.5792 | Longitude van het zoekpunt |
| radius | 600 | Gevraagde straal in meters |
| limit | 10 | Gevraagde limiet van resultaten |
| modes | bus,tram | Gezochte vervoerswijzen |

Deze coördinaten worden gebruikt als voorbeeldzoekopdracht in Bordeaux; ze garanderen geen halte. Raadpleeg het [OpenAPI ROOTE contract](https://api.roote.ai/openapi.json) voor de actuele grenzen, velden en voorwaarden.

## Eerste verzoek uitvoeren aan serverzijde

Hier is een JavaScript voorbeeld voor een Node.js omgeving met fetch. De token, als jouw toegang er een gebruikt, blijft in een serveromgeving omgevingsvariabele. Het voorbeeld vereist geen geheim in de browser te plaatsen.

```
async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
  const url = new URL('https://api.roote.ai/v1/transit/nearby');
  url.search = new URLSearchParams({
    lat: '44.8378',
    lng: '-0.5792',
    radius: '600',
    limit: '10',
    modes: 'bus,tram'
  }).toString();

  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;

  const response = await fetch(url, {
    headers,
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) {
    throw new Error(`Erreur HTTP ${response.status}`);
  }

  const data = await response.json();
  if (data.contract_version !== 'roote-1.0.0') {
    throw new Error('Version du contrat non reconnue');
  }
  if (!['success', 'empty', 'partial'].includes(data.status)) {
    throw new Error('Recherche indisponible');
  }
  if (!Array.isArray(data.stations)) {
    throw new Error('Réponse sans collection stations valide');
  }

  return {
    status: data.status,
    stations: data.stations,
    lines: data.lines,
    operators: data.operators,
    coverage: data.coverage,
    warnings: data.warnings,
    attributions: data.attributions,
    meta: data.meta
  };
}
```

Het geraadpleegde contract voorziet in anonieme of token toegang, afhankelijk van toepasselijk beleid. Controleer je rechten en toegangsbeperkingen. Een correcte HTTP respons betekent niet automatisch correcte inhoud; valideer in productie ook de objecten tegen het schema.

## Lees de entiteiten en hun relaties

De collectie stations bevat de teruggegeven plekken. Bekijk voor ieder vooral id, name, entity_kind, location en distance_meters. De referenties line_ids en operator_ids verbinden met de collecties lines en operators indien aanwezig.

Toon een geografische afstand als zodanig. Zet deze niet om naar looptijd zonder routeberekening. De gids [een halte in de buurt vinden](https://www.roote.ai/nl/guides/hoe-vind-je-het-dichtstbijzijnde-bus-of-tramhalte/) legt uit waarom toegangspunten de werkelijke verplaatsing kunnen beïnvloeden.

Behandel ook onbekende informatie expliciet. In het contract kan accessibility.wheelchair unknown zijn: deze waarde betekent noch yes noch no. Een aangemelde vertrekmogelijkheid is geen vertreklijst.

## Toon een lijst of kaart

Gebruik het ID om interface-elementen stabiel te houden, de naam voor label, en location voor positie. Koppel lijnen via referenties in plaats van naamvergelijking.

Als je kleuren of labels van lijnen uit data gebruikt, behandel die als externe invoer die gevalideerd moet worden. Gebruik voor namen tekst, geen geïnjecteerde HTML.

Behoud bronvermeldingen en toon die welke het contract verplicht stelt.

## Resultaat zonder data, gedeeltelijke respons en fouten afhandelen

Een empty resultaat zegt dat er geen resultaat is binnen het bekende bereik. Het bewijst niet afwezigheid van vervoer. Een partial respons kan nuttige plekken tonen en tegelijkertijd beperkingen melden: toon resultaten en passende waarschuwing.

Lees coverage, warnings en toegepaste beperkingen in meta. Een afgeknotte lijst is geen volledige dekking. Bij netwerk- of HTTP fouten, toon onbeschikbaarheid zonder het resultaat door 'geen haltes' te vervangen.

Voor 429 codes, volg herstartinstructies en mogelijke headers. Vermijd oneindige herhaalfouten.

## Stations, zones en perrons onderscheiden

Het veld entity_kind onderscheidt verschillende plaatseniveaus. Twee nabije resultaten kunnen aparte perrons zijn; twee vergelijkbare namen kunnen uit verschillende bronnen komen.

Fuseer plekken niet louter op nabijheid. Gebruik diensten gedocumenteerde relaties en identiteiten. Onze gids [GTFS, GTFS-RT en GBFS](https://www.roote.ai/nl/guides/gtfs-gtfs-rt-en-gbfs-wat-zijn-de-verschillen/) legt de context van de data uit.

## Voorbereiden voor productie-integratie

Start zoekopdrachten als locatie of filters nuttig veranderen. Groepeer identieke oproepen, stel timeout in en pas cache aan op type data en dienstcondities.

Een lijst van plekken en realtime beschikbaarheid hebben verschillende versheidseisen. Test de flow met complete, lege, gedeeltelijke en foutieve antwoorden voordat je de zoekfunctie uitrolt.

## Zoekopdracht uitbreiden naar stedelijke diensten

Haltes en stedelijke diensten gebruiken aparte routes. Om toiletten rond hetzelfde punt te zoeken, gebruikt de GET route /v1/services/nearby lat en lon, met types=toilets. Stuur geen modes=toilets naar deze route: dit vocabulaire hoort bij de kaart-URL, niet bij de Services-filter.

Het volgende JavaScript voorbeeld bouwt een Services-URL voor een straal van 600 meter. Het start de aanvraag niet; hergebruik de HTTP- en contractcontroles zoals eerder beschreven. De verwachte collectie wordt services, in plaats van stations. Behoud service_type, location, distance_meters en de werkelijk aanwezige attributen.

Het REST-contract documenteert onder andere toilets, drinking_water, fountain, wifi, parking, charging, aed en locker. De typen die door de MCP worden aangeboden kunnen verschillen. Raadpleeg het schema van de gebruikte interface voor toegestane parameters, hun grenzen en uw toegangsbeperkingen.

De attributen van een dienst garanderen niet dat deze open is op het moment van zoeken. Onbekende toegankelijkheid betekent niet dat een dienst onbereikbaar is; een lege lijst door een fout bewijst niet dat er geen toiletten zijn. Houd de data per familie gescheiden in plaats van ze te reduceren tot een naam en een punt.

Voor een gecombineerde kaart koppelt u de resultaten aan hun familie en IDs. Toon een Services-fout zonder de haltes van Transit te verwijderen. De zoekopdracht blijft gecentreerd op hetzelfde punt, maar statussen en dekking kunnen verschillen.

```
const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
  lat: '44.8416106', lon: '-0.5810938',
  radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());
```

[Een lege of foutieve zoekopdracht diagnosticeren](https://www.roote.ai/nl/guides/geen-resultaat-of-api-fout-verschil-maken/)

[Een gefilterde kaart direct integreren op een website](https://www.roote.ai/nl/guides/kaart-mobiliteit-integreren-site/)

[Een assistent bouwen rond deze zoekopdrachten](https://www.roote.ai/nl/guides/hoe-een-assistent-te-maken-die-mobiliteit-rond-een-adres-vindt/)

## Veelgestelde vragen

### Heeft Nearby de volgende vertrekken?

Niet in het hier beschreven contract. Deze route vindt plekken met openbaar vervoer; vertrekken vragen een aparte mogelijkheid.

### Kan ik na een fout een lege lijst tonen?

Toon een onbeschikbaarheid. Een fout bewijst niet dat er geen haltes zijn.

### Mag de API-token in de browser?

Een geheim blijft op de server. Gebruik het toegangsschema dat voor jouw applicatie en account is bedoeld.