# Paano maghanap ng mga hintuan ng transportasyon malapit gamit ang isang API?

> Alamin kung paano maghanap ng mga malalapit na hintuan gamit ang ROOTE API: koordinado, radius, halimbawa ng JavaScript, pagbasa ng mga resulta at pamamahala ng mga error.

Source: https://www.roote.ai/fil/guides/paano-maghahanap-ng-mga-hintuan-ng-transportasyon-malapit-gamit-ang-api/
Language: fil
Author: ROOTE

Para maghanap ng mga hintuan sa paligid ng isang punto, ipadala ang latitude, longitude at radius nito sa isang proximity API. Suriin muna ang status ng tugon, mga entidad na ibinalik, at impormasyon ng coverage bago ipakita ang listahan o mapa.

Sa kontratang ROOTE roote-1.0.0, ang ruta GET /v1/transit/nearby ay naghahanap ng mga lugar ng transportasyon malapit. Hindi nito kinukuha ang mga pag-alis o mga alerto sa real-time. Ang paghahanap ng lugar at paghahanap ng susunod nitong dumaan ay dalawang magkaibang operasyon.

## Itakda ang mga parameter

Ang query ay gumagamit ng lat para sa latitude at lng para sa longitude. Ang alias na lon ay nakasaad din sa kontrata. Ang parameter na radius ay nagpapahayag ng radius sa metro; ang limit ay nagtatalaga ng bilang ng hinihinging resulta. Maaaring tukuyin ng filter na modes ang mga mode ng transportasyon.

| Parameter | Halimbawa | Kahulugan |
| --- | --- | --- |
| lat | 44.8378 | Latitude ng punto ng paghahanap |
| lng | -0.5792 | Longitude ng punto ng paghahanap |
| radius | 600 | Hininging radius sa metro |
| limit | 10 | Hiniging limitasyon ng resulta |
| modes | bus,tram | Hinahanap na mga mode |

Ang mga koordinadong ito ay halimbawa ng paghahanap sa Bordeaux; hindi ito nangangahulugan ng isang garantisadong hintuan. Tingnan ang [kontrata ng OpenAPI ROOTE](https://api.roote.ai/openapi.json) para sa kasalukuyang mga limitasyon, mga field at kondisyon.

## Magpadala ng unang kahilingan sa server-side

Narito ang isang halimbawa ng JavaScript para sa environment ng Node.js na may fetch. Ang token, kung gumagamit ka nito, ay naka-imbak bilang environment variable sa server-side. Hindi kailangan ng halimbawa na maglagay ng lihim sa browser.

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

Pinapayagan ng kontratang tiningnan ang anonymous o token access, depende sa mga patakarang ipinapatupad. Suriin ang iyong mga karapatan at mga limitasyon sa access. Ang tamang tugon sa HTTP ay hindi pumapalya na beripikahin ang nilalaman nito; sa produksiyon, gumamit din ng pag-validate ng mga object laban sa schema.

## Basahin ang mga entidad at kanilang relasyon

Ang koleksyon ng stations ay naglalaman ng mga ibinalik na lugar. Para sa bawat isa, suriin lalo na ang id, name, entity_kind, location at distance_meters. Ang mga reference na line_ids at operator_ids ay nag-uugnay sa mga koleksyon ng lines at operators kapag may laman.

Ipakita ang isang heograpikong distansya bilang ganoon. Huwag itong gawing oras ng paglalakad nang walang kalkulasyon ng ruta. Ang gabay na [paghahanap ng malapit na hintuan](https://www.roote.ai/fil/guides/paano-makahanap-ng-pinakamalapit-na-hintuan-ng-bus-o-tram/) ay nagpapaliwanag kung bakit ang mga access ay maaaring makaapekto sa actual na paggalaw.

Gawing malinaw na iproseso rin ang hindi alam na impormasyon. Sa kontrata, maaaring ang accessibility.wheelchair ay may halagang unknown: hindi ito nangangahulugang yes o no. Ang isang kapasidad ng mga anunsyadong pag-alis ay hindi kumakatawan sa listahan ng mga pag-alis.

## Ipakita bilang listahan o mapa

Gamitin ang identifier upang panatilihing matatag ang mga elemento ng interface, ang pangalan para sa kanilang label at location para sa kanilang posisyon. Iugnay ang mga linya gamit ang mga reference kaysa itugma ayon sa pangalan.

Kung nagpapakita ka ng mga kulay ng linya o mga label mula sa data, tratuhin ang mga ito bilang panlabas na input na kailangang beripikahin. Para sa mga pangalan, gumamit ng teksto sa halip na ipasok ang HTML.

Panatilihin ang mga attribution ng source at ipakita ang mga ipinapakita ng kontrata bilang kinakailangan.

## Pamahalaan ang walang laman na resulta, partial na tugon, at error

Ang isang empty na resulta ay tumutukoy sa paghahanap na walang naibalik na resulta sa kilalang saklaw. Hindi nito pinatutunayan ang pisikal na kawalan ng transportasyon. Ang isang partial na tugon ay maaaring maglaman ng kapaki-pakinabang na mga lugar habang nagbababala tungkol sa mga limitasyon: ipakita ang mga resulta at angkop na babala.

Basahin ang coverage, warnings, at mga limitasyong inilapat sa meta. Ang putol na listahan ay hindi nangangahulugang kumpletong saklaw. Sa kaso ng network o HTTP error, ipakita ang hindi magagamit, nang hindi pinapalitan ang resulta ng “walang hintuan”.

Para sa code 429, sundin ang mga panuto sa pagre-retry at posibleng mga header ng serbisyo. Iwasan ang paulit-ulit na pagsubok na walang tigil.

## Ihiwalay ang stations, zones, at platforms

Ang field na entity_kind ay nagtatakda ng iba’t ibang antas ng mga lugar. Dalawang magkalapit na resulta ay maaaring tumukoy sa magkakaibang platforms; ang dalawang magkatulad na pangalan ay maaaring mula sa magkakaibang mga source.

Huwag awtomatikong pagsamahin ang mga lugar batay lamang sa kalapitan. Gamitin ang mga relasyon at pagkakakilanlan na dokumentado ng serbisyo. Ang aming gabay na [GTFS, GTFS-RT at GBFS](https://www.roote.ai/fil/guides/gtfs-gtfs-rt-at-gbfs-anong-kakaiba/) ay nagpapaliwanag ng konteksto ng mga datos.

## Ihanda ang integrasyon sa produksiyon

Simulan ang mga paghahanap kapag naaayos ang posisyon o mga filter sa kapaki-pakinabang na paraan. Pagsamahin ang mga magkaparehong tawag, magtakda ng timeout, at iakma ang cache ayon sa uri ng data at kundisyon ng serbisyo.

Ang isang listahan ng mga lugar at real-time na availability ay may iba't ibang mga kinakailangan sa pagiging bago. Beripikahin ang proseso gamit ang kumpleto, walang laman, partial, at error na mga tugon bago ipakita ang paghahanap sa mga gumagamit.

## Palawakin ang paghahanap sa mga serbisyong urban

Ang mga hinto at serbisyo sa lungsod ay gumagamit ng magkahiwalay na ruta. Para maghanap ng mga palikuran malapit sa parehong punto, ang GET /v1/services/nearby na ruta ay nangangailangan ng lat at lon, kasama ang types=toilets. Huwag magpadala ng modes=toilets sa rutang ito: ang bokabularyong ito ay para sa URL ng mapa, hindi para sa Services filter.

Ang sumusunod na halimbawa sa JavaScript ay bumubuo ng URL para sa Services na may radius na 600 metro. Hindi nito pinapagana ang request; gamitin ang HTTP at kontratang mga kontrol na naunang ipinaliwanag. Ang inaasahang koleksyon ay nagiging services, sa halip na stations. Panatilihin ang service_type, location, distance_meters at mga attribute na tunay na naroroon.

Ang REST kontrata ay dokumentado lalo na ang toilets, drinking_water, fountain, wifi, parking, charging, aed at locker. Maaaring mag-iba ang mga uri na ipinapakita ng MCP. Para sa mga tinatanggap na parametro, mga hangganan nito at mga limitasyon ng iyong access, sumangguni sa schema ng interface na ginagamit.

Ang mga attribute ng isang serbisyo ay hindi nagpapakita ng katiyakan kung bukas ito sa panahon ng paghahanap. Ang hindi kilalang accessibility ay hindi nangangahulugang hindi ma-access ang serbisyo; ang walang laman na listahan na resulta ng error ay hindi nagpapatunay ng kawalan ng palikuran. Panatilihin ang datos na angkop sa bawat pamilya sa halip na gawing iisa lamang pangalan at punto.

Para sa pinagsamang mapa, iugnay ang mga resulta sa kanilang pamilya at mga identifier. Ipakita ang error sa Services nang hindi binubura ang mga hinto na naibalik ng Transit. Ang paghahanap ay nananatiling nakasentro sa parehong punto, ngunit maaaring magkakaiba ang mga status at coverage.

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

[Pagsusuri sa walang laman o may error na paghahanap](https://www.roote.ai/fil/guides/walang-resulta-o-error-sa-api-paano-makalaman/)

[Direktang pag-integrate ng naka-filter na mapa sa isang site](https://www.roote.ai/fil/guides/paano-maglagay-ng-mapa-ng-mobility-sa-sariling-site/)

[Paggawa ng assistant base sa mga paghahanap na ito](https://www.roote.ai/fil/guides/paano-gumawa-ng-assistant-na-naghahanap-ng-mobilidad-sa-paligid-ng-address/)

## Mga Kadalasang Itanong

### Nagbibigay ba ang Nearby ng susunod na mga pag-alis?

Hindi sa kontratang ipinakita dito. Ang rutang ito ay naghahanap ng mga lugar ng transportasyon; ang mga pag-alis ay nangangailangan ng hiwalay na kakayahan.

### Maari bang magpakita ng walang laman na listahan pagkatapos ng error?

Ipakita ang hindi magagamit. Ang error ay hindi patunay ng kawalan ng mga hintuan.

### Maari bang ilagay ang API token sa browser?

Ang lihim ay dapat manatiling sa server-side. Gamitin ang access model na inilaan para sa iyong aplikasyon at account.