Kostenlose Geokodierungs-API: Vorwärts-, Rückwärts- und Entfernungsmessung in einem REST-Aufruf

Ihre Liefer-App muss für die Weiterleitung eine Straßenadresse in Breiten- und Längengrade umwandeln. Die Google Maps Geocoding API kostet 5 $ pro 1.000 Anfragen. Für ein Startup, das 10.000 Lieferungen durchführt pro Tag, das sind allein für die Geokodierung 50 $/Tag.

Die Botoi-Geo-API deckt Vorwärts-Geokodierung, Rückwärts-Geokodierung und Entfernungsberechnung ab drei REST-Endpunkte. Der anonyme Zugriff bearbeitet 100 Anfragen pro Tag kostenlos. Bezahlte Pläne Beginnen Sie bei 9 $/Monat und decken Sie alle über 150 Endpunkte der Plattform ab, nicht nur die Geokodierung.

Geokodierung weiterleiten: Adresse an Koordinaten

Der /v1/geo/geocode Der Endpunkt nimmt eine Straßenadresse und gibt den Breitengrad zurück. Längengrad und eine standardisierte Adresse. Eine POST-Anfrage:

curl -X POST https://api.botoi.com/v1/geo/geocode \\
  -H "Content-Type: application/json" \\
  -d '{"address": "1600 Amphitheatre Parkway, Mountain View, CA"}'

Antwort:

{
  "success": true,
  "data": {
    "latitude": 37.4224764,
    "longitude": -122.0842499,
    "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    "place_name": "Googleplex",
    "country": "United States",
    "country_code": "US"
  }
}

Die Antwort umfasst den Ländercode, den Ortsnamen (sofern verfügbar) und a formatted_address Zeichenfolge, die Sie als kanonische Version speichern können. Teilweise Adressen funktionieren auch; Die API löst „Mountain View, CA“ in Koordinaten für das Stadtzentrum auf.

Umgekehrte Geokodierung: Koordinaten zur Adresse

Eine mobile App erfasst einen GPS-Stecknadelabwurf. Für die Quittung benötigen Sie eine für Menschen lesbare Adresse. Der /v1/geo/reverse Endpunkt nimmt Breiten- und Längengrad und unterbricht die Ergebnis in strukturierte Komponenten:

curl -X POST https://api.botoi.com/v1/geo/reverse \\
  -H "Content-Type: application/json" \\
  -d '{"latitude": 37.4224, "longitude": -122.0842}'

Antwort:

{
  "success": true,
  "data": {
    "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    "street": "Amphitheatre Pkwy",
    "house_number": "1600",
    "city": "Mountain View",
    "state": "California",
    "postal_code": "94043",
    "country": "United States",
    "country_code": "US"
  }
}

Jedes Feld ist getrennt: Straße, Hausnummer, Stadt, Bundesland, Postleitzahl und Land. Sie müssen keine einzige Zeichenfolge analysieren, um die Stadt oder Postleitzahl zu extrahieren.

Entfernungsberechnung zwischen zwei Punkten

Der /v1/geo/distance Endpunkt berechnet den Großkreisabstand zwischen zwei Koordinatenpaare. Es werden sowohl Kilometer als auch Meilen zurückgegeben:

curl -X POST https://api.botoi.com/v1/geo/distance \\
  -H "Content-Type: application/json" \\
  -d '{"from": {"lat": 37.7749, "lng": -122.4194}, "to": {"lat": 34.0522, "lng": -118.2437}}'

Antwort:

{
  "success": true,
  "data": {
    "distance_km": 559.12,
    "distance_miles": 347.42,
    "from": { "lat": 37.7749, "lng": -122.4194 },
    "to": { "lat": 34.0522, "lng": -118.2437 }
  }
}

San Francisco nach Los Angeles: 559 km. Die Berechnung verwendet die Haversine-Formel, die gibt Ihnen die geradlinige Entfernung über die Erdoberfläche an. Für Näherungsfilter, Lieferung Radiusprüfungen und Funktionen zur Filialsuche, das ist die richtige Messgröße.

Praxisbeispiel: Adressvalidierung an der Kasse

Ein Kunde gibt „123 Fake Stret, Nowhereville“ in Ihr Checkout-Formular ein. Syntaxvalidierung geht durch, weil es wie eine Adresse aussieht. Geokodierung fängt das Problem. Wenn die API dies nicht kann Wenn Sie die Adresse in Koordinaten auflösen, ist die Adresse wahrscheinlich ungültig.

async function validateAddress(address) {
  const res = await fetch("https://api.botoi.com/v1/geo/geocode", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.BOTOI_API_KEY,
    },
    body: JSON.stringify({ address }),
  });

  const { success, data } = await res.json();

  if (!success || !data.latitude) {
    return { valid: false, suggestion: null };
  }

  return {
    valid: true,
    formatted: data.formatted_address,
    coordinates: {
      lat: data.latitude,
      lng: data.longitude,
    },
  };
}

// Usage in a checkout form handler
const result = await validateAddress("1600 Amphitheatre Parkway, Mountain View");

if (!result.valid) {
  // Show error: "We couldn't verify this address. Check for typos."
}

// Use result.formatted as the canonical address
// Use result.coordinates for delivery routing

Dieser Ansatz erkennt Tippfehler, nicht vorhandene Straßennamen und unvollständige Adressen ein Paket ins Nirgendwo verschicken. Der formatted_address Feld gibt Ihnen die standardisierte Version zur Speicherung in Ihrer Datenbank.

Praxisbeispiel: Filialsuche

Finden Sie anhand der Koordinaten eines Benutzers (von der Browser-Geolokalisierung oder einer geokodierten Adresse) die drei nächstgelegene Geschäfte:

async function findNearestStore(userLat, userLng, stores) {
  // Calculate distance from user to each store in parallel
  const distances = await Promise.all(
    stores.map(async (store) => {
      const res = await fetch("https://api.botoi.com/v1/geo/distance", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Api-Key": process.env.BOTOI_API_KEY,
        },
        body: JSON.stringify({
          from: { lat: userLat, lng: userLng },
          to: { lat: store.lat, lng: store.lng },
        }),
      });

      const { data } = await res.json();
      return { ...store, distance_km: data.distance_km };
    })
  );

  // Sort by distance and return the closest 3
  return distances
    .sort((a, b) => a.distance_km - b.distance_km)
    .slice(0, 3);
}

const stores = [
  { name: "Downtown", lat: 37.7849, lng: -122.4094 },
  { name: "Mission Bay", lat: 37.7699, lng: -122.3894 },
  { name: "Sunset", lat: 37.7549, lng: -122.4894 },
];

const nearest = await findNearestStore(37.7749, -122.4194, stores);
// Returns stores sorted by distance from the user

Für eine kleine Anzahl von Geschäften (unter 50) funktionieren parallele API-Aufrufe gut. Für Hunderte von Standorte, führen Sie die Haversine-Berechnung clientseitig durch und verwenden Sie die API nur für die Geokodierung Schritt.

Praxisbeispiel: Lieferradius-Check

Eine Essensliefer-App muss Bestellungen außerhalb eines Umkreises von 25 km um die Küche ablehnen. Überprüfen der Abstand vor Annahme der Bestellung:

async function isWithinDeliveryRadius(
  warehouseLat, warehouseLng,
  customerLat, customerLng,
  maxRadiusKm
) {
  const res = await fetch("https://api.botoi.com/v1/geo/distance", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.BOTOI_API_KEY,
    },
    body: JSON.stringify({
      from: { lat: warehouseLat, lng: warehouseLng },
      to: { lat: customerLat, lng: customerLng },
    }),
  });

  const { data } = await res.json();

  return {
    eligible: data.distance_km <= maxRadiusKm,
    distance_km: data.distance_km,
  };
}

// Check if a customer is within 25 km of the warehouse
const check = await isWithinDeliveryRadius(
  37.7749, -122.4194,  // warehouse
  37.3382, -121.8863,  // customer in San Jose
  25                    // 25 km radius
);

if (!check.eligible) {
  console.log(
    \`Customer is \\\${check.distance_km.toFixed(1)} km away. Outside delivery zone.\`
  );
}

Die Prüfung erfordert einen API-Aufruf und erfolgt in weniger als 100 ms. Kombinieren Sie es mit der Vorwärtsgeokodierung um in zwei aufeinanderfolgenden Anfragen von einer eingegebenen Adresse zu einer Entscheidung über die Zustellberechtigung zu gelangen.

Wichtige Punkte

• /v1/geo/geocode Konvertiert Straßenadressen in Breiten-/Längengrade mit a standardisierte formatierte Adresse. Funktioniert mit Teiladressen und Ortsnamen.
• /v1/geo/reverse Konvertiert Koordinaten in eine strukturierte Adresse mit separatem Felder für Straße, Ort, Bundesland, Postleitzahl und Land.
• /v1/geo/distance berechnet den Großkreisabstand zwischen zwei Punkten mit die Haversine-Formel. Gibt sowohl km als auch Meilen zurück.
• Der anonyme Zugriff ermöglicht 5 Anfragen pro Minute und 100 pro Tag. Kein API-Schlüssel erforderlich für Tests oder Verwendung in geringem Umfang.
• Alle drei Endpunkte akzeptieren JSON und geben es zurück. Keine Abfragezeichenfolgenkodierung, kein XML-Parsing, nein SDK-Installation. Jede Sprache mit einem HTTP-Client funktioniert.