# Jalgrataste saadavus reaalajas: kuidas seda rakenduses kuvada?

> Kuva jalgrataste saadavus ROOTE API abil: ajatempli, värskuse, teadmata väärtuste, värskenduse ja aegunud andmete haldamine rakenduses.

Source: https://www.roote.ai/et/guides/ratsevalised-jalgrataste-reaalajas-saadavus-kuidas-rakenduses-naita/
Language: et
Author: ROOTE

Jalgrataste reaalajas saadavuse kuvamiseks rakenduses seo tagatud arvuga vastava värskuse ja sõiduvahendi võtmise võimalustega. Vaatlus kirjeldab, mida allikas mingil hetkel teadis; see ei taga, et ratta saabumishetkel veel saadaval on.

ROOTE liikumiskokkulepe eristab jaamad, üksikud sõiduvahendid ja nende seisundid. Liides peab neid erinevusi tõlkima, vältides teadmata väärtuse, tühja jaama või ajutiselt kättesaamatu allika segamini ajamist.

## Jaama ja üksiku sõiduvahendi eristamine

Jaam võib näidata rattaloendureid ja tagastamise kohti. Üksikul sõiduvahendil on saadavusseisund ja võimalikud lisainfo. Vältige jaama lugemist rattaks või sama laoseisu topeltarvestamist.

ROOTE liikumise DTO-s võivad availability.bikes ja availability.docks olla teadmata. Võimsus- või akuvälju tuleks kuvada ainult siis, kui need eksisteerivad ja tõlgendatakse vastavalt kokkuleppele.

[ROOTE OpenAPI leping](https://api.roote.ai/openapi.json)

## Värskuse ja ajatemplitest lugemine

| Väli | Tõlgendus |
| --- | --- |
| freshness.state | Seisundi teade: fresh, stale, unknown või static |
| freshness.source_updated_at | Allika värskendamise kuupäev, kui teada |
| freshness.received_at | Lepingus märgitud vastuvõtu kuupäev |
| freshness.expires_at | Kehtivuse tähtaeg, kui teada |
| availability.bikes | Teadaolev kogus või teadmata väärtus |
| pickup.enabled ja pickup.state | Andmed rattavõtmisest jaamas |

Sinu päringu aeg ei ole automaatselt vaatlusaja märk. Kella 10-s saadud tulemus võib sisaldada allikat, mis värskendati kell 9:45. Ära kuva „just värskendatud“ ainult põhinedes liidese vastuvõtu ajale.

## Erinevate kuvaseisundite etteplaneerimine

| Saadud andmed | Planeeritav kuvamine |
| --- | --- |
| Teadaolev kogus ja värske andmestik | Vaatluskogus ja ajatempli näit |
| Kogus on null | Ühtegi ratast ei täheldatud, koos ajakontekstiga |
| Kogus nullväärtus | Saadavus teadmata |
| Stale seisund või aegumistähtaeg ületatud | Vana andmestik; soovita uuendust |
| pickup.enabled=false | Võtmine pole saadaval kuigi loendur on positiivne |
| Otsinguviga | Saadavus ajutiselt puudub, ära muuda oluliseks nulliks |

Ära loe unknown või static seisundit värskeks. Jaamainfo võib olla stabiilne, kuigi loendur muutub kiiresti. Säilita hoiatused ja nõutavad atribuudid vastuses.

## Normeerimise näide enne kuvamist

Järgnev funktsioon annab kuvamise seisundi jaamast, mis on juba ROOTE skeemi järgi valideeritud. See ei ole täielik vastuse valideerija. Nähtavad sildid peaksid tulema su liidese tõlke võtmetest.

```
function availabilityView(station, now = Date.now()) {
  const freshness = station.freshness;
  const expiresAt = freshness.expires_at
    ? Date.parse(freshness.expires_at) : null;
  const expired = expiresAt !== null &&
    Number.isFinite(expiresAt) && expiresAt <= now;
  if (station.pickup.enabled === false ||
      station.pickup.state === 'unavailable_now') {
    return { state: 'pickup_unavailable', count: null };
  }
  if (expired || freshness.state === 'stale') {
    return { state: 'stale', count: null };
  }
  const count = station.availability.bikes;
  if (freshness.state !== 'fresh' || count === null ||
      !Number.isFinite(count) || count < 0) {
    return { state: 'unknown', count: null };
  }
  return {
    state: count === 0 ? 'empty' : 'observed', count,
    sourceUpdatedAt: freshness.source_updated_at,
    receivedAt: freshness.received_at,
    pickupState: station.pickup.state
  };
}
```

Isegi observed seisundiga ära muuda pickupState=unknown kinnitatuks võtmiseks. Loendur on keelutõendus. Kuvage võtmise kontekst, kui toode aitab kasutajal jaama valida.

## Värskenda ilma tarbetute korduvate päringuteta

Kohanda värskendust avaldatud aegumise, teenuse tingimuste ja kasutaja käitumise järgi. Gruppige sarnased päringud, vältige taustakõnesid inaktiivsel lehel ja tühistage otsingu asenduskõned.

Kohalik vahemälu viide ei näita allika värskust. Pärast viga võid säilitada viimase kuupäevastatud vaatluse, kui su liides kuvab selle selgelt vanana. Ära eemalda seda vahet ka esimese õnnestunud korduvärskenduse järel, kui allikas püsib stale.

## Sideme mõistmine GBFS-iga

GBFS kirjeldab jagatud liikumisteenuseid ja nende avaldatud seisundit. Otsene integratsioon peab tõlgendama faile, versiooni ja voo ajatempleid. Standarditud API puhul kasuta API lepingut; ära lisa GBFS välja, mida vastuses ei oodata.

[Valik GTFS, GTFS Realtime ja GBFS vahel](https://www.roote.ai/et/guides/gtfs-gtfs-rt-ja-gbfs-mis-on-eraldised/)

## Testi olukordi, mis võivad lugejat eksitada

Katseta reaalset nulli, teadmata väärtust, aegunud tähtaega, keelatud võtmist ja vigadega tulemuse järel. Kontrolli ka kuupäevatsoone. Positiivne loendur ei tohi kunagi kuvada „ratas reserveeritud“ ja kättesaamatus ei tohi jätta välja nikerdatud nulli.

[Tühi vastus ja vigade käsitlemine](https://www.roote.ai/et/guides/mitte-ulemust-v%C3%B5i-api-viga-kuidas-eristada/)

[Rakenda need reeglid tehisintellekti abilisena](https://www.roote.ai/et/guides/kuidas-luua-assistent-mobiliteedile-aadressi-lahedal/)

[Kasutusjuhend rattale leidmiseks](https://www.roote.ai/et/guides/kuidas-leida-linnaratast-lahkliigiks-ligidal/)

## Korduma kippuvad küsimused

### Kas positiivne kogus tagab ratta minu saabumiseks?

Ei. See kirjeldab vaatlust, mis võib muutuda otsingu ja saabumise vahel.

### Kas nulli võib asendada nulliga?

Ei. Null tähistab teadmata väärtust; null on teada kogus ja omab teistsugust tähendust.

### Kas tuleb värskendada iga paari sekundi tagant?

Kasuta kehtivusnäidiseid, teenuse piiranguid ja oma liidese vajadusi. Suvaline sagedus ei taga allika värskust.