# Kā meklēt tuvumā esošās transporta pieturas, izmantojot API?

> Atklājiet tuvumā esošo pieturu meklēšanu ar ROOTE API: koordinātas, rādiuss, JavaScript piemērs, rezultātu lasīšana un kļūdu apstrāde.

Source: https://www.roote.ai/lv/guides/kads-meklet-transporta-pieturas-netala-ar-api/
Language: lv
Author: ROOTE

Lai meklētu pieturas ap kādu punktu, nododiet tā platumu, garumu un rādiusu tuvuma API. Pēc tam pārbaudiet atbildes statusu, atgrieztās vienības un pārklājuma informāciju, pirms parādāt sarakstu vai karti.

ROOTE līgumā roote-1.0.0 maršruts GET /v1/transit/nearby atklāj tuvumā esošās transporta vietas. Tas neiegūst tiešsaistes izbraukšanas vai brīdinājumus. Vietas meklēšana un nākamā pieturas laika meklēšana ir divas atsevišķas operācijas.

## Parametru definēšana

Pieprasījumā tiek izmantoti lat platumam un lng garumam. Alias lon arī ir aprakstīts līgumā. Parametrs radius norāda rādiusu metros; limit ierobežo pieprasīto rezultātu skaitu. Kustību filtru modes var precizēt transporta veidus.

| Parametrs | Piemērs | Nozīme |
| --- | --- | --- |
| lat | 44.8378 | Meklēšanas punkta platums |
| lng | -0.5792 | Meklēšanas punkta garums |
| radius | 600 | Pieprasītais rādiuss metros |
| limit | 10 | Pieprasītais rezultātu limits |
| modes | bus,tram | Meklētie transporta veidi |

Šīs koordinātas ir piemērs meklēšanai Bordo; tās negarantē konkrētu pieturu. Skatiet [ROOTE OpenAPI līgumu](https://api.roote.ai/openapi.json) pašreizējām robežām, laukiem un nosacījumiem.

## Nosūtīt pirmo pieprasījumu servera pusē

Šeit ir JavaScript piemērs Node.js vidē ar fetch. Ja piekļuve prasa žetonu, tas tiek glabāts servera vides mainīgajā. Piemēram nav nepieciešams likt noslēpumu pārlūkprogrammā.

```
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
  };
}
```

Apskatītais līgums paredz anonīmu vai žetona piekļuvi atkarībā no piemērojamajām politikām. Pārbaudiet savas tiesības un piekļuves ierobežojumus. Pareiza HTTP atbilde neaizstāj saturu pārbaudi; ražošanā lietojiet arī objektu validāciju pret shēmu.

## Lasīt vienības un to attiecības

Staciju kolekcija satur atgrieztās vietas. Katram aplūkojiet jo īpaši id, name, entity_kind, location un distance_meters. Atsauces line_ids un operator_ids ļauj sasaistīt līniju un operatoru kolekcijas, ja tās ir pieejamas.

Rādiet ģeogrāfisko attālumu kā tādu. Nepārvērtējiet to par gājiena laiku bez maršruta aprēķina. Ceļvedis [atrast tuvāko pieturu](https://www.roote.ai/lv/guides/kadas-atrast-tuvako-autobusa-vai-tramvaja-pieturu/) paskaidro, kā piekļuve var ietekmēt reālo pārvietošanos.

Īpaši apstrādājiet arī nezināmas informācijas vērtības. Līgumā accessibility.wheelchair var būt unknown: šī vērtība nav ne yes, ne no. Paziņotā izbraukšanas kapacitāte nav izbraukšanas saraksts.

## Rādīt sarakstu vai karti

Lietojiet identifikatoru saskarnes elementu stabilizēšanai, nosaukumu to nosaukšanai un location - pozīcijas noteikšanai. Sasaistiet līnijas pēc attiecīgajām atsaucēm, nevis nosaukumu līdzības.

Ja rādāt līniju krāsas vai nosaukumus no datiem, uzskatiet tos par ārējām ievadēm, kurām jāveic validācija. Nosaukumiem lietojiet tekstu, ne injicētu HTML.

Saglabājiet datu avotu piedēvējumus un rādiet tos, kurus līgums nosaka kā obligātus.

## Apstrādāt tukšu rezultātu, daļēju atbildi un kļūdu

Rezultāts empty apraksta meklēšanu bez rezultātiem zināmā apgabalā. Tas nepierāda fizisku transporta neesamību. Partial atbilde var saturēt noderīgas vietas, vienlaikus norādot ierobežojumus: rādiet rezultātus un attiecīgu brīdinājumu.

Lasiet coverage, warnings un meta pielietotos ierobežojumus. Samazināts saraksts nav pilnīgs pārklājums. Tīkla vai HTTP kļūdas gadījumā rādiet nepieejamību, neaizstājot rezultātu ar “nav pieturu”.

Kods 429 prasa ievērot atkāpšanās norādījumus un iespējamos pakalpojuma galvenes. Izvairieties no atkārtotām sūknēšanas vaicāšanas cikliem.

## Atšķirt pieturas, zonas un peronus

Lauks entity_kind atšķir vairākus vietu līmeņus. Divi tuvumā esoši rezultāti var būt dažādi peroni; divi līdzīgi nosaukumi var piederēt dažādiem avotiem.

Nesapludiniet vietas tikai pēc tuvuma. Lietojiet pakalpojuma dokumentētās attiecības un identitātes. Mūsu ceļvedis [GTFS, GTFS-RT un GBFS](https://www.roote.ai/lv/guides/gtfs-gtfs-rt-un-gbfs-kadas-atskiribas/) izskaidro datu kontekstu.

## Sagatavot ražošanas integrāciju

Veiciet meklēšanu, kad pozīcija vai filtri mainās būtiski. Apvienojiet identiskos pieprasījumus, definējiet gaidīšanas laiku un pielāgojiet kešatmiņu datu veidam un pakalpojuma apstākļiem.

Vietu sarakstam un reāllaika pieejamībai ir atšķirīgas svaiguma prasības. Pārbaudiet attiecības ar pilnīgām, tukšām, daļējām un kļūdainām atbildēm pirms meklēšanas parādīšanas lietotājiem.

## Izplatīt meklēšanu uz pilsētas pakalpojumiem

Pieturas un pilsētas pakalpojumi izmanto atšķirīgas maršrutu ceļus. Lai meklētu tualetes ap to pašu punktu, GET /v1/services/nearby gaida lat un lon, ar types=toilets. Nesūtiet modes=toilets šim maršrutam: šis termins pieder kartes URL, nevis Pakalpojumu filtra ietvaros.

Nākamais JavaScript piemērs veido Pakalpojumu URL meklēšanas rādiusā 600 metru. Tas neveicina pieprasījumu; atkārtoti izmantojiet minētos HTTP un līguma kontroļus. Sagaidāmais kolekcijas nosaukums ir services, nevis stations. Saglabājiet service_type, location, distance_meters un patiesi esošos atribūtus.

REST līgums dokumentē īpaši toilets, drinking_water, fountain, wifi, parking, charging, aed un locker. MCP atklātie tipi var atšķirties. Pieņemto parametru, to robežu un piekļuves ierobežojumu gadījumā skatiet izmantotā interfeisa shēmu.

Pakalpojuma atribūti negarantē tā pieejamību meklēšanas brīdī. Nezināma pieejamība nenozīmē, ka pakalpojums nav pieejams; tukša saraksta rezultāts kļūdas gadījumā nepierāda tualešu neesamību. Saglabājiet datus katras kategorijas ietvaros vietā to apvienošanai vārdā un punktā.

Kombinētai kartei saistiet rezultātus ar to kategoriju un identifikatoriem. Rādiet Pakalpojumu kļūdu bez Transit atgriezto pieturu dzēšanas. Meklēšana joprojām ir vērsta uz to pašu punktu, bet stāvokļi un pārklājumi var atšķirties.

```
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());
```

[Diagnosticēt tukšu vai kļūdainu meklēšanu](https://www.roote.ai/lv/guides/nav-rezultatu-apis-klaidu-atpazisana/)

[Tieši integrēt filtrētu karti mājaslapā](https://www.roote.ai/lv/guides/kartu-mobilitati-integret-sava-lapaa/)

[Izveidot palīgu ap šīm meklēšanām](https://www.roote.ai/lv/guides/kako-izveidot-palidzetaju-kas-atrod-mobilitate-ap-adresi/)

## Biežāk uzdotie jautājumi

### Vai Nearby rāda nākamās izbraukšanas?

Nē, šajā līgumā ne. Šis maršruts atklāj transporta vietas, izbraukšanas prasa atsevišķu iespēju.

### Vai kļūdas gadījumā var rādīt tukšu sarakstu?

Rādiet nepieejamību. Kļūda nepierāda pieturu neesamību.

### Vai API žetonu var likt pārlūkprogrammā?

Noslēpums jāglabā servera pusē. Lietojiet paredzēto piekļuves modeli savai lietojumprogrammai un kontam.