# Πώς να αναζητήσετε στάσεις μεταφοράς κοντά με ένα API;

> Ανακαλύψτε την αναζήτηση στάσεων κοντά σας με το API ROOTE: συντεταγμένες, ακτίνα, παράδειγμα JavaScript, ανάγνωση αποτελεσμάτων και διαχείριση σφαλμάτων.

Source: https://www.roote.ai/el/guides/pos-na-mporeite-na-vriskete-staseis-metanaston-meso-enos-api/
Language: el
Author: ROOTE

Για να αναζητήσετε στάσεις γύρω από ένα σημείο, μεταβιβάστε το γεωγραφικό πλάτος, το γεωγραφικό μήκος και μια ακτίνα σε ένα API γειτονιάς. Ελέγξτε μετά την κατάσταση της απάντησης, τις επιστρεφόμενες οντότητες και τις πληροφορίες κάλυψης πριν εμφανίσετε τη λίστα ή τον χάρτη.

Στο συμβόλαιο ROOTE roote-1.0.0, η διαδρομή GET /v1/transit/nearby εντοπίζει μέρη μεταφοράς κοντά. Δεν ανακτά αναχωρήσεις ή ειδοποιήσεις σε πραγματικό χρόνο. Η αναζήτηση ενός μέρους και η αναζήτηση της επόμενης διέλευσης είναι δύο ξεχωριστές λειτουργίες.

## Ορισμός παραμέτρων

Το αίτημα χρησιμοποιεί lat για το γεωγραφικό πλάτος και lng για το γεωγραφικό μήκος. Το ψευδώνυμο lon περιγράφεται επίσης στο συμβόλαιο. Η παράμετρος radius εκφράζει την ακτίνα σε μέτρα· το limit οριοθετεί τον αριθμό των ζητούμενων αποτελεσμάτων. Το φίλτρο modes μπορεί να προσδιορίσει τα μέσα μεταφοράς.

| Παράμετρος | Παράδειγμα | Σημασία |
| --- | --- | --- |
| lat | 44.8378 | Γεωγραφικό πλάτος του σημείου αναζήτησης |
| lng | -0.5792 | Γεωγραφικό μήκος του σημείου αναζήτησης |
| radius | 600 | Ζητούμενη ακτίνα σε μέτρα |
| limit | 10 | Ζητούμενο όριο αποτελεσμάτων |
| modes | bus,tram | Ζητούμενοι τρόποι μεταφοράς |

Αυτές οι συντεταγμένες χρησιμεύουν ως παράδειγμα αναζήτησης στο Μπορντό· δεν υποδεικνύουν εγγυημένη στάση. Ελέγξτε το [συμβόλαιο OpenAPI ROOTE](https://api.roote.ai/openapi.json) για τα τρέχοντα όρια, πεδία και προϋποθέσεις.

## Αποστολή πρώτου αιτήματος από την πλευρά του διακομιστή

Εδώ είναι ένα παράδειγμα JavaScript για περιβάλλον Node.js που διαθέτει fetch. Το token, εάν η πρόσβασή σας χρησιμοποιεί, παραμένει σε μεταβλητή περιβάλλοντος από την πλευρά διακομιστή. Το παράδειγμα δεν απαιτεί να τοποθετήσετε κάποιο μυστικό στον περιηγητή.

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

Το συμβόλαιο προβλέπει ανώνυμη πρόσβαση ή με token, ανάλογα με τις εφαρμόσιμες πολιτικές. Ελέγξτε τα δικαιώματά σας και τα όρια πρόσβασης. Μια σωστή HTTP απάντηση δεν απαλλάσσει από την επαλήθευση του περιεχομένου· σε παραγωγή, χρησιμοποιήστε επίσης επικύρωση αντικειμένων βάσει του σχήματος.

## Ανάγνωση οντοτήτων και των σχέσεών τους

Η συλλογή stations περιέχει τα επιστρεφόμενα μέρη. Για κάθε ένα, συμβουλευτείτε ιδιαίτερα τα id, name, entity_kind, location και distance_meters. Οι αναφορές line_ids και operator_ids επιτρέπουν τη σύνδεση με τις συλλογές lines και operators όταν είναι διαθέσιμες.

Εμφανίστε μια γεωγραφική απόσταση ως έχει. Μην την μετατρέπετε σε χρόνο πεζοπορίας χωρίς υπολογισμό διαδρομής. Ο οδηγός [βρείτε μια κοντινή στάση](https://www.roote.ai/el/guides/pos-na-vrisete-ton-prosego-stathmo-leoforeiou-hram/) εξηγεί γιατί οι προσβάσεις μπορεί να αλλάξουν την πραγματική μετακίνηση.

Επεξεργαστείτε επίσης τις άγνωστες πληροφορίες ρητά. Στο συμβόλαιο, accessibility.wheelchair μπορεί να έχει την τιμή unknown: αυτή η τιμή δεν ισοδυναμεί ούτε με yes ούτε με no. Μια ικανότητα ανακοινωμένων αναχωρήσεων δεν αποτελεί λίστα αναχωρήσεων.

## Εμφάνιση λίστας ή χάρτη

Χρησιμοποιήστε το αναγνωριστικό για να σταθεροποιήσετε τα στοιχεία της διεπαφής, το όνομα για την ετικέτα τους και τη θέση για τη θέση τους. Συνδέστε τις γραμμές μέσω των αναφορών, αντί να πλησιάζετε τα ονόματά τους.

Αν εμφανίζετε χρώματα γραμμών ή ετικέτες από τα δεδομένα, θεωρήστε τα ως εξωτερικές εισόδους που πρέπει να επικυρωθούν. Για τα ονόματα, χρησιμοποιήστε κείμενο αντί για ενσωματωμένο HTML.

Διατηρήστε τις αναφορές πηγών και εμφανίστε εκείνες που το συμβόλαιο δηλώνει ως απαιτούμενες.

## Διαχείριση κενών αποτελεσμάτων, μερικής απάντησης και λάθους

Ένα αποτέλεσμα empty περιγράφει μια αναζήτηση χωρίς αποτελέσματα εντός του γνωστού πεδίου. Δεν αποδεικνύει τη φυσική απουσία μέσων μεταφοράς. Μια απάντηση partial μπορεί να περιέχει χρήσιμα μέρη ενώ υποδεικνύει περιορισμούς: παρουσιάστε τα αποτελέσματα και την κατάλληλη προειδοποίηση.

Διαβάστε coverage, warnings και τα όρια που εφαρμόζονται στο meta. Μια αποκομμένη λίστα δεν αποτελεί πλήρη κάλυψη. Σε περίπτωση δικτυακού ή HTTP σφάλματος, εμφανίστε μη διαθεσιμότητα, χωρίς να αντικαταστήσετε το αποτέλεσμα με «καμία στάση».

Για κωδικό 429, συμβουλευτείτε τις οδηγίες επανεκκίνησης και τυχόν επικεφαλίδες της υπηρεσίας. Αποφύγετε συνεχή επαναλήψεις.

## Διαχωρισμός στάσεων, ζωνών και αποβαθρών

Το πεδίο entity_kind διακρίνει διάφορα επίπεδα τοποθεσιών. Δύο γειτονικά αποτελέσματα μπορεί να αντιστοιχούν σε διαφορετικές αποβάθρες· δύο παρόμοια ονόματα μπορεί να ανήκουν σε διαφορετικές πηγές.

Μην συγχωνεύετε αυτόματα μέρη μόνο με βάση την εγγύτητα. Χρησιμοποιήστε τις σχέσεις και τα ταυτότητες που τεκμηριώνει η υπηρεσία. Ο οδηγός μας [GTFS, GTFS-RT και GBFS](https://www.roote.ai/el/guides/gtfs-gtfs-rt-kai-gbfs-poies-einai-oi-diaforeis/) εξηγεί το πλαίσιο των δεδομένων.

## Προετοιμασία για ενσωμάτωση στην παραγωγή

Ενεργοποιήστε τις αναζητήσεις όταν αλλάζει ουσιαστικά η θέση ή τα φίλτρα. Ομαδοποιήστε ίδιες κλήσεις, ορίστε ένα χρονικό όριο και προσαρμόστε την κρυφή μνήμη ανάλογα με τον τύπο δεδομένων και τις συνθήκες υπηρεσίας.

Μια λίστα με μέρη και η διαθεσιμότητα σε πραγματικό χρόνο δεν έχουν τις ίδιες απαιτήσεις φρεσκάδας. Επικυρώστε τη διαδρομή με πλήρεις, κενές, μερικές και σφάλματα απαντήσεις πριν παρουσιάσετε την αναζήτηση στους χρήστες.

## Επέκταση της αναζήτησης σε αστικές υπηρεσίες

Οι στάσεις και οι αστικές υπηρεσίες χρησιμοποιούν διαφορετικές διαδρομές. Για να αναζητήσετε τουαλέτες γύρω από το ίδιο σημείο, η διαδρομή GET /v1/services/nearby περιμένει lat και lon, με types=toilets. Μην στέλνετε modes=toilets σε αυτή τη διαδρομή: αυτή η ορολογία ανήκει στο URL του χάρτη και όχι στο φίλτρο Υπηρεσίες.

Το παρακάτω παράδειγμα JavaScript κατασκευάζει ένα URL Υπηρεσιών για μια ακτίνα 600 μέτρων. Δεν εκκινεί το αίτημα· επαναχρησιμοποιήστε τους HTTP και συμβατικούς ελέγχους που περιγράφηκαν παραπάνω. Η αναμενόμενη συλλογή γίνεται services, αντί για stations. Διατηρήστε τα service_type, location, distance_meters και τα πραγματικά παρόντα χαρακτηριστικά.

Το REST συμβόλαιο τεκμηριώνει μεταξύ άλλων τα toilets, drinking_water, fountain, wifi, parking, charging, aed και locker. Οι τύποι που εκτίθενται από τον MCP μπορεί να διαφέρουν. Για τις δεκτές παραμέτρους, τα όριά τους και τους περιορισμούς της πρόσβασής σας, συμβουλευτείτε το σχήμα της χρήσης του interface.

Τα χαρακτηριστικά μιας υπηρεσίας δεν εγγυώνται τη λειτουργία της τη στιγμή της αναζήτησης. Μια άγνωστη προσβασιμότητα δεν ισοδυναμεί με μη προσβάσιμη υπηρεσία· μια κενή λίστα λόγω σφάλματος δεν αποδεικνύει απουσία τουαλετών. Κρατήστε τα δεδομένα ξεχωριστά ανά οικογένεια αντί να τα περιορίζετε σε όνομα και σημείο.

Για συνδυασμένο χάρτη, συνδέστε τα αποτελέσματα με την οικογένειά τους και τα αναγνωριστικά τους. Εμφανίστε σφάλμα Υπηρεσιών χωρίς να σβήνετε τις στάσεις που επέστρεψε ο Transit. Η αναζήτηση παραμένει κεντραρισμένη στο ίδιο σημείο, αλλά τα στατιστικά και η κάλυψη μπορεί να διαφέρουν.

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

[Διάγνωση κενής ή λανθασμένης αναζήτησης](https://www.roote.ai/el/guides/%CE%BA%CE%B1%CE%BD%CE%B5-%CE%B4%CE%B9%CE%B1%CE%BA%CF%81%CE%B9%CF%83%CE%B7-%CE%BC%CE%B5%CF%84%CE%B1%CE%BE%CF%85-%CE%B1%CF%80%CE%BF%CF%85%CF%83%CE%B9%CE%B1%CF%82-%CE%B1%CF%80%CE%BF%CF%84%CE%B5%CE%BB%CE%B5%CF%83%CE%BC%CE%B1%CF%84%CE%BF%CF%82-%CE%BA%CE%B1%CE%B9-%CE%BB%CE%B1%CE%B8%CE%BF%CF%85%CF%82-api/)

[Ενσωμάτωση ενός φιλτραρισμένου χάρτη απευθείας σε μια ιστοσελίδα](https://www.roote.ai/el/guides/pos-na-entaxteis-xarti-kinhshs-sto-sito-sas/)

[Κατασκευή βοηθού γύρω από αυτές τις αναζητήσεις](https://www.roote.ai/el/guides/poso-na-dimiourgiso-voitho-pou-vrisketai-mobilita-gia-mia-dieuthinsi/)

## Συχνές ερωτήσεις

### Παρέχει το Nearby τις επόμενες αναχωρήσεις;

Όχι στο παρουσιαζόμενο εδώ συμβόλαιο. Αυτή η διαδρομή ανιχνεύει μέρη μεταφοράς· οι αναχωρήσεις απαιτούν ξεχωριστή δυνατότητα.

### Μπορώ να εμφανίσω κενή λίστα μετά από λάθος;

Εμφανίστε μη διαθεσιμότητα. Ένα λάθος δεν αποδεικνύει απουσία στάσεων.

### Μπορώ να τοποθετήσω το token API στον περιηγητή;

Ένα μυστικό πρέπει να μένει στην πλευρά διακομιστή. Χρησιμοποιήστε το πρότυπο πρόσβασης που προβλέπεται για την εφαρμογή και τον λογαριασμό σας.