# Pyörien saatavuus reaaliajassa: miten näyttää se sovelluksessa?

> Näytä pyörien saatavuus ROOTE-rajapinnalla: aikaleimat, tuoreus, tuntemattomat arvot, päivitykset ja vanhentuneet tiedot sovelluksessasi.

Source: https://www.roote.ai/fi/guides/pyorien-saatavuutta-reaaliajassa-sovelluksessa/
Language: fi
Author: ROOTE

Näyttääksesi pyörien reaaliaikaisen saatavuuden sovelluksessa yhdistä palautettu määrä sen tuoreuteen ja ajoneuvon noutomahdollisuuksiin. Havainto kuvaa, mitä lähde tiesi hetkellä; se ei takaa, että pyörä on yhä saatavilla perille saapuessa.

ROOTE-liikkumissopimus erottaa asemat, yksittäiset ajoneuvot ja niiden tilat. Rajapinnan tulee tulkita nämä erot ilman, että se sekoittaa tuntematonta arvoa, tyhjää asemaa tai tilapäisesti poissa olevaa lähdettä.

## Erotetaan asema ja yksittäinen ajoneuvo

Asema voi näyttää pyörien ja palautuspaikkojen lukumäärät. Yksittäisellä ajoneuvolla on käytettävyystila ja muita mahdollisia tietoja. Vältä aseman laskemista pyöräksi tai samojen varastojen laskureiden yhteenlaskemista.

ROOTE-mobiilidatansiirrossa (DTO) availability.bikes ja availability.docks voivat olla tuntemattomia. Voimanlähde- tai akun kenttiä tulisi näyttää vain, jos ne ovat olemassa ja tulkitaan sopimuksen mukaisesti.

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

## Tuoreuden ja aikaleimojen lukeminen

| Kenttä | Tulkinta |
| --- | --- |
| freshness.state | Ilmoitettu tila: fresh, stale, unknown tai static |
| freshness.source_updated_at | Lähteen päivityspäivämäärä, jos tiedossa |
| freshness.received_at | Vastaanottopäivämäärä, sopimuksen mukaan ilmoitettu |
| freshness.expires_at | Voimassaolon päättymispäivä ilmoitettu, jos tiedossa |
| availability.bikes | Tunnettu määrä tai tuntematon arvo |
| pickup.enabled ja pickup.state | Tietoa pyörän noudosta asemalta |

Kutsusi aika ei automaattisesti ole havaintoaika. Klo 10 vastaanotettu tulos voi sisältää lähteen päivityksen klo 9.45. Älä näytä ”päivitetty nyt” pelkän rajapinnan vastaanottoajan perusteella.

## Suunnittele erilliset näyttötilat

| Vastaanotettu tieto | Näyttötapaus |
| --- | --- |
| Tunnettu määrä ja tuore data | Havaittu määrä ja ajallinen viittaus |
| Määrä nolla | Ei havaittuja pyöriä, aikatieto mukana |
| Määrä null | Tuntematon saatavuus |
| Stale-tila tai vanhentunut aikaraja | Vanha data; ehdota päivitystä |
| pickup.enabled=false | Nouto ei saatavilla, vaikka laskuri olisi positiivinen |
| Hakutieto virheellinen | Saatavuus väliaikaisesti poissa, ei muunneta nollaksi |

Älä luokittele unknown- tai static-tilaa tuoreeksi. Asematieto voi olla vakaa, vaikka laskuri vaihtuu nopeasti. Säilytä myös vastauksen edellyttämät varoitukset ja määrittelyt.

## Esimerkki normalisoinnista ennen näyttöä

Seuraava funktio tuottaa käyttötilan jo ROOTE-mallin mukaisesti validoidusta asemasta. Se ei ole täydellinen vastaustarkistin. Näkyvien tekstien tulee tulla käyttöliittymän käännösavaimista.

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

Vaikka tila olisi observed, älä muuta pickupState=unknown noudoksi varmaksi. Laskuri pysyy havaintona. Näytä noutotiedot, jos tuotteesi auttaa käyttäjää valitsemaan aseman.

## Päivitä ilman turhia kutsujen määrän lisäämisiä

Säädä päivitystiheys julkaistun vanhentumisajan, palvelun ehtojen ja käyttäjän toiminnan mukaan. Ryhmittele toistuvat pyynnöt, vältä taustakutsuja passiivisella sivulla ja peruuta korvaavat haut.

Paikallinen välimuistiviive ei todista lähteen tuoreutta. Virheen jälkeen voit säilyttää viimeisen päivätyn havainnon, jos käyttöliittymä esittää sen selvästi vanhentuneena. Älä poista tätä eroa ensimäisen onnistuneen haun jälkeen, jos lähde on yhä stale-tilassa.

## Ymmärrä yhteys GBFS:ään

GBFS kuvaa yhteiskäyttöliikenteen palvelut ja niiden julkaistut tilat. Suora integraatio vaatii tiedostojen, version ja aikaleimojen tulkintaa. Käytä vakioitua rajapintaa; älä lisää GBFS-kenttää, jota ei vastauksessa ole.

[Valitse GTFS, GTFS Realtime ja GBFS välillä](https://www.roote.ai/fi/guides/gtfs-gtfsrt-ja-gbfs-mika-erot/)

## Testaa lukijan harhaanjohtavat tilanteet

Kokeile todellista nollaa, tuntematonta arvoa, vanhentunutta aikarajaa, poissa olevaa noutoa ja virhettä pätevän tuloksen jälkeen. Tarkista myös aikavyöhykkeiden näyttö. Positiivinen laskuri ei saa näyttää ”pyörä varattu” ja saatavuuden poissaolo ei saa näyttää tekaistua nollaa.

[Käsittele tyhjät vastaukset ja virheet](https://www.roote.ai/fi/guides/ei-tulosta-tai-api-virhe-kuinka-eroittaa/)

[Sovella sääntöjä tekoälyavustajassa](https://www.roote.ai/fi/guides/kuinka-luoda-liikkumisavustaja-osoitteen-ymparille/)

[Käyttäjäopas pyörän löytämiseen](https://www.roote.ai/fi/guides/miten-loydaan-lahiseudun-jakopyora-roote/)

## Usein kysytyt kysymykset

### Takaaanko positiivinen määrä pyörän perille saapuessa?

Ei. Se kuvaa havaintoa, joka voi muuttua haun ja saapumisesi välillä.

### Voiko nullin korvata nollalla?

Ei. Null tarkoittaa tuntematonta arvoa; nolla on tunnettu määrä, jolla on eri merkitys.

### Pitäisikö päivittää muutaman sekunnin välein?

Käytä voimassaolo-ohjeita, palvelun rajoja ja käyttöliittymän vaatimuksia. Satunnainen päivitystiheys ei takaa tuoreempaa lähdettä.