# Jinsi ya Kutafuta Vituo vya Usafiri Karibu kwa kutumia API?

> Jifunze jinsi ya kutafuta vituo vya usafiri vinavyokaribu kwa kutumia API ya ROOTE: kuratibu, mduara, mfano wa JavaScript, kusoma matokeo na usimamizi wa makosa.

Source: https://www.roote.ai/sw/guides/kujitafuta-mahali-pa-usafiri-karibu-nawe-ukitumia-api/
Language: sw
Author: ROOTE

Ili kutafuta vituo karibu na eneo fulani, tumia latitudo, longitudo, na mduara kwenye API ya karibu. Kisha hakiki hali ya jibu, vitu vilivyorejeshwa, na taarifa za upatikanaji kabla ya kuonyesha orodha au ramani.

Katika mkataba wa ROOTE roote-1.0.0, njia GET /v1/transit/nearby hupata maeneo ya usafiri yalioko karibu. Haipati taarifa za kuondoka au arifa za muda halisi. Kutafuta eneo na kutafuta wakati wa kuondoka ni operesheni mbili tofauti.

## Tangaza vigezo

Ombi linatumia lat kwa latitudo na lng kwa longitudo. Jina la nambari lon pia linaelezwa katika mkataba. Kipengele radius kinaonyesha mduara kwa mita; limit hutawala idadi ya matokeo yanayoombwa. Chujio modes kinaweza kubainisha aina za usafiri.

| Kipengele | Mfano | Maelezo |
| --- | --- | --- |
| lat | 44.8378 | Latitudo ya eneo la utafutaji |
| lng | -0.5792 | Longitudo ya eneo la utafutaji |
| radius | 600 | Mduara unaoombwa kwa mita |
| limit | 10 | Kiwango cha matokeo yanayoombwa |
| modes | bus,tram | Aina za usafiri zinazotafutwa |

Kuratibu hizi ni mifano ya utafutaji Bordeaux; hazimaanishi ni kituo kilicho hakikiwa. Angalia [mkataba wa OpenAPI wa ROOTE](https://api.roote.ai/openapi.json) kwa mipaka, mashamba na masharti ya sasa.

## Tuma ombi la kwanza upande wa seva

Huu ni mfano wa JavaScript kwa mazingira ya Node.js ambayo ina fetch. Ishara ya ufikiaji, ikiwa inahitajika, hifadhiwa katika mabadiliko ya mazingira upande wa seva. Mfano hauhitaji kuweka siri katika kivinjari.

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

Mkataba uliosomwa unaruhusu ufikiaji bila kujulikana au kwa kutumia ishara, kulingana na sera zinazotumika. Hakiki haki zako na mipaka ya ufikiaji. Jibu halali la HTTP halaiti kusahihisha yaliyomo; kwa matumizi ya uzalishaji, tumia uthibitishaji wa vitu dhidi ya muundo pia.

## Soma vitu na uhusiano wao

Kukusanya kwa vituo kunajumuisha maeneo yaliyorejeshwa. Kwa kila kimoja, hakiki hasa id, name, entity_kind, location na distance_meters. Marejeleo ya line_ids na operator_ids yanaruhusu kuunganisha makusanyo ya lines na operators endapo yanapatikana.

Onyesha umbali wa jiografia kama ulivyo. Usibadilishe kuwa muda wa kutembea bila kuhesabu njia. Mwongozo wa [kupata kituo kilicho karibu](https://www.roote.ai/sw/guides/jinsi-ya-kuwapata-kituo-cha-basi-au-tram-kilicho-karibu-sana/) unaeleza kwa nini njia za kuingia zinaweza kubadilisha usafiri halisi.

Pia zingatia taarifa zisizojulikana wazi. Katika mkataba, accessibility.wheelchair inaweza kuwa unknown: thamani hii haimaanishi ndio au hapana. Uwezo wa kuondoka uliotangazwa si orodha ya kuondoka.

## Onyesha orodha au ramani

Tumia kitambulisho kuimarisha vipengele vya kiolesura, jina kwa lebo yao na location kwa nafasi yao. Unganisha mistari kwa kutumia marejeleo, badala ya kulinganisha majina yao.

Ikiwa unaonyesha rangi za mistari au lebo kutoka data, zitunze kama pembejeo za nje za kuthibitisha. Kwa majina, tumia maandishi badala ya HTML iliyoongezwa.

Hifadhi rasilimali za vyanzo na onyesha zile ambazo mkataba unasema ni lazima.

## Shughulikia matokeo tupu, majibu ya sehemu na makosa

Matokeo empty yanaelezea utafutaji usio na matokeo ndani ya eneo linalojulikana. Haamaanishi usafiri haupo kimwili. Jibu partial linaweza kuwa na maeneo yanayofaa huku likitoa tahadhari kuhusu mipaka: onyesha matokeo pamoja na onyo linalofaa.

Soma coverage, warnings na mipaka inayotekelezwa katika meta. Orodha iliyokatwa si maelezo ya upatikanaji kamili. Katika hitilafu ya mtandao au HTTP, onyesha upatikana mdogo bila kubadilisha matokeo kuwa “hakuna kituo”.

Kwa msimbo wa 429, angalia maelekezo ya kurejea na vichwa vya huduma vinavyoweza kuwepo. Epuka kufanya majaribio yanayorudia kwa mzunguko.

## Tofautisha vituo, maeneo na mabaraza

Shamba entity_kind hutoa tofauti kati ya viwango mbalimbali vya maeneo. Matokeo mawili karibu yanaweza kuwa mabaraza tofauti; majina mawili yanayofanana yanaweza kutoka vyanzo tofauti.

Usiunganishwe kiotomati maeneo kwa kutumia umbali tu. Tumii uhusiano na watambulisho vinavyodhibitishwa na huduma. Mwongozo wetu [GTFS, GTFS-RT na GBFS](https://www.roote.ai/sw/guides/tofauti-kati-ya-gtfs-gtfs-rt-na-gbfs/) unaelezea mazingira ya data.

## Tayarisha ushirikiano kwa matumizi ya uzalishaji

Anzisha utafutaji wakati nafasi au vichujio vinapobadilika kwa maana. Kusanya miito sawa, weka muda wa kusubiri na rekebisha cache kwa aina ya data na hali ya huduma.

Orodha ya maeneo na upatikanaji wa muda halisi havihitaji ubora sawa wa upya. Hakiki mchakato kwa majibu kamili, tupu, sehemu na makosa kabla ya kuonesha utafutaji kwa watumiaji.

## Panua utafutaji kwa huduma za miji

Maeneo ya kusimama na huduma za miji hutumia njia tofauti. Kutafuta vyoo karibu na sehemu ile ile, njia ya GET /v1/services/nearby inatarajia lat na lon, na types=toilets. Usitume modes=toilets kwa njia hii: msamiati huu ni wa URL ya ramani, sio kichujio cha Huduma.

Mfano wa JavaScript ufuatao huunda URL ya Huduma kwa mduara wa mita 600. Hauchochei ombi hilo; tumia tena udhibiti wa HTTP na mikataba iliyotajwa hapo juu. Mkusanyiko unaotarajiwa post resi services, badala ya stations. Hifadhi service_type, location, distance_meters na sifa zilizo hapo kweli.

Mkataba wa REST unaelezea hasa toilets, drinking_water, fountain, wifi, parking, charging, aed na locker. Aina zinazotolewa na MCP zinaweza kutofautiana. Kwa vigezo vinavyokubalika, mipaka yao na vikwazo vya ufikiaji wako, rejea chati ya kiolesura kinachotumika.

Sifa za huduma hazihakikishi kuwa huduma iko wazi wakati wa utafutaji. Ukosefu wa taarifa si sawa na huduma kutokuwepo; orodha tupu kutokana na hitilafu haionyeshi ukosefu wa vyoo. Hifadhi data kwa familia kila moja badala ya kuzifupisha kwa jina na nukta.

Kwa ramani iliyochanganywa, sambaza matokeo kwa familia yao na vitambulisho. Onyesha kosa la Huduma bila kufuta maeneo yaliyorudishwa na Transit. Utafutaji bado unaongozwa na sehemu ile ile, lakini hali na mawasiliano yanaweza kutofautiana.

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

[Tambua tatizo la utafutaji tupu au lenye hitilafu](https://www.roote.ai/sw/guides/hakuna-matokeo-au-kosa-la-api-jinsi-ya-kujitofautisha/)

[Jumuisha ramani iliyochujwa moja kwa moja kwenye tovuti](https://www.roote.ai/sw/guides/jinsi-ya-kujumuisha-ramani-ya-usafiri-kwenye-tovuti-yako/)

[Tengeneza msaidizi wa mzunguko wa utafutaji huu](https://www.roote.ai/sw/guides/kujenga-msaidizi-wa-kipata-usalama-wa-mobility-katika-anwani/)

## Maswali yanayoulizwa mara kwa mara

### Je Nearby hutoa kuondoka vijavyo?

Hapana katika mkataba huu. Njia hii hutafuta maeneo ya usafiri; kuondoka kunahitaji uwezo tofauti.

### Je tunaweza kuonyesha orodha tupu baada ya kosa?

Onyesha upatikanaji mdogo. Kosa halithibitishi kwamba hapana vituo.

### Je tunaweza kuweka tokeni ya API kwenye kivinjari?

Siri inapaswa kubaki upande wa seva. Tumia mfumo wa ufikiaji uliopangwa kwa ajili ya programu yako na akaunti yako.