API de géocodage gratuite : avant, arrière et distance en un seul appel REST

Votre application de livraison doit convertir une adresse postale en latitude et longitude pour l'acheminement. L'API de géocodage de Google Maps coûte 5 $ pour 1 000 requêtes. Pour une startup effectuant 10 000 livraisons par jour, cela représente 50 $/jour rien que pour le géocodage.

L'API botoi geo couvre le géocodage direct, le géocodage inverse et le calcul de distance avec trois points de terminaison REST. L'accès anonyme traite 100 demandes par jour sans frais. Forfaits payants commencez à 9 $/mois et couvrez les plus de 150 points de terminaison de la plate-forme, pas seulement le géocodage.

Géocodage direct : adresse aux coordonnées

La /v1/geo/geocode le point de terminaison prend une adresse postale et renvoie la latitude, longitude et une adresse formatée standardisée. Une requête POST :

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

Réponse:

{
  "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"
  }
}

La réponse comprend le code du pays, le nom du lieu (si disponible) et un formatted_address chaîne que vous pouvez stocker comme version canonique. Partielle aborde également le travail ; l'API résout "Mountain View, CA" en coordonnées du centre-ville.

Géocodage inversé : coordonnées à adresser

Une application mobile capture une chute de broche GPS. Vous avez besoin d'une adresse lisible par l'homme pour le reçu. Le /v1/geo/reverse le point final prend la latitude et la longitude et rompt le résultat en composants structurés :

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

Réponse:

{
  "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"
  }
}

Chaque champ est séparé : rue, numéro de maison, ville, état, code postal et pays. Vous n'avez pas besoin d'analyser une seule chaîne pour extraire la ville ou le code postal.

Calcul de distance entre deux points

La /v1/geo/distance le point final calcule la distance orthodromique entre deux paires de coordonnées. Il renvoie à la fois des kilomètres et des miles :

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}}'

Réponse:

{
  "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 à Los Angeles : 559 km. Le calcul utilise la formule Haversine, qui vous donne la distance en ligne droite à travers la surface de la Terre. Pour filtres de proximité, livraison contrôles de rayon et fonctionnalités de localisation de magasin, c'est la bonne mesure.

Exemple pratique : validation de l'adresse à la caisse

Un client tape « 123 Fake Stret, Nowhereville » dans votre formulaire de paiement. Validation de la syntaxe passe parce que cela ressemble à une adresse. Le géocodage résout le problème. Si l'API ne peut pas résolvez l'adresse en coordonnées, l'adresse est probablement invalide.

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

Cette approche détecte les fautes de frappe, les noms de rues inexistants et les adresses incomplètes avant vous. expédier un colis nulle part. Le formatted_address le champ vous donne le version standardisée à stocker dans votre base de données.

Exemple pratique : localisateur de magasin

Étant donné les coordonnées d'un utilisateur (issues de la géolocalisation du navigateur ou d'une adresse géocodée), retrouvez les trois magasins les plus proches :

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

Pour un petit nombre de magasins (moins de 50), les appels API parallèles fonctionnent bien. Pendant des centaines de emplacements, effectuez le calcul Haversine côté client et utilisez l'API uniquement pour le géocodage étape.

Exemple pratique : contrôle du rayon de livraison

Une application de livraison de nourriture doit rejeter les commandes en dehors d’un rayon de 25 km autour de la cuisine. Vérifier la distance avant d'accepter la commande :

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.\`
  );
}

La vérification prend un appel API et revient en moins de 100 ms. Combinez-le avec le géocodage avancé passer d'une adresse tapée à une décision d'éligibilité à la livraison en deux requêtes séquentielles.

Points clés

• /v1/geo/geocode convertit les adresses postales en latitude/longitude avec un adresse formatée standardisée. Fonctionne avec des adresses partielles et des noms de lieux.
• /v1/geo/reverse convertit les coordonnées en une adresse structurée avec des champs pour la rue, la ville, l’état, le code postal et le pays.
• /v1/geo/distance calcule la distance orthodromique entre deux points en utilisant la formule Haversine. Renvoie à la fois les kilomètres et les miles.
• L'accès anonyme permet 5 requêtes par minute et 100 par jour. Aucune clé API requise pour tests ou utilisation à faible volume.
• Les trois points de terminaison acceptent et renvoient JSON. Pas de codage de chaîne de requête, pas d'analyse XML, non Installation du SDK. N'importe quelle langue avec un client HTTP fonctionne.