API de geocodificación gratuita: avance, retroceso y distancia en una llamada REST

Su aplicación de entrega necesita convertir una dirección postal en latitud y longitud para la ruta. La API de codificación geográfica de Google Maps cuesta 5 dólares por cada 1000 solicitudes. Para una startup que realiza 10.000 entregas por día, eso son $50 por día solo en codificación geográfica.

La API de botoi geo cubre la geocodificación directa, la geocodificación inversa y el cálculo de distancia con tres puntos finales REST. El acceso anónimo maneja 100 solicitudes por día sin costo alguno. Planes pagos comience en $ 9 al mes y cubra los más de 150 puntos finales de la plataforma, sin solo la codificación geográfica.

Geocodificación directa: dirección a coordenadas

La /v1/geo/geocode El punto final toma una dirección postal y devuelve latitud, longitud y una dirección con formato estandarizado. Una solicitud POST:

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

Respuesta:

{
  "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 respuesta incluye el código del país, el nombre del lugar (cuando esté disponible) y un formatted_address cadena que puedes almacenar como la versión canónica. Parcial las direcciones también funcionan; la API resuelve "Mountain View, CA" en las coordenadas del centro de la ciudad.

Geocodificación inversa: coordenadas para dirigirse

Una aplicación móvil captura la caída de un pin de GPS. Necesita una dirección legible por humanos para el recibo. El /v1/geo/reverse El punto final toma la latitud y la longitud y rompe el resultado en componentes estructurados:

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

Respuesta:

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

Cada campo está separado: calle, número de casa, ciudad, estado, código postal y país. No es necesario analizar una sola cadena para extraer la ciudad o el código postal.

Cálculo de distancia entre dos puntos.

La /v1/geo/distance El punto final calcula la distancia del gran círculo entre dos pares de coordenadas. Devuelve tanto kilómetros como millas:

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

Respuesta:

{
  "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 a Los Ángeles: 559 km. El cálculo utiliza la fórmula de Haversine, que te da la distancia en línea recta a través de la superficie de la Tierra. Para filtros de proximidad, entrega comprobaciones de radio y funciones de localización de tiendas, esta es la métrica correcta.

Ejemplo práctico: validación de dirección al finalizar la compra

Un cliente escribe "123 Fake Stret, Nowhereville" en su formulario de pago. Validación de sintaxis pasa porque parece una dirección. La geocodificación detecta el problema. Si la API no puede resuelva la dirección en coordenadas, es probable que la dirección no sea válida.

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

Este enfoque detecta errores tipográficos, nombres de calles inexistentes y direcciones incompletas antes de que usted enviar un paquete a ninguna parte. El formatted_address El campo te da la versión estandarizada para almacenar en su base de datos.

Ejemplo práctico: localizador de tiendas

Dadas las coordenadas de un usuario (desde la geolocalización del navegador o una dirección geocodificada), encuentre los tres tiendas más cercanas:

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

Para una pequeña cantidad de tiendas (menos de 50), las llamadas API paralelas funcionan bien. Por cientos de ubicaciones, realice el cálculo de Haversine en el lado del cliente y use la API solo para la codificación geográfica paso.

Ejemplo práctico: verificación del radio de entrega

Una aplicación de entrega de comida necesita rechazar pedidos fuera de un radio de 25 km desde la cocina. comprobar la distancia antes de aceptar el pedido:

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 verificación requiere una llamada API y regresa en menos de 100 ms. Combínalo con codificación geográfica directa para pasar de una dirección escrita a una decisión de elegibilidad de entrega en dos solicitudes secuenciales.

Puntos clave

• /v1/geo/geocode convierte direcciones de calles a latitud/longitud con un dirección con formato estandarizado. Funciona con direcciones parciales y nombres de lugares.
• /v1/geo/reverse convierte coordenadas a una dirección estructurada con separado campos para calle, ciudad, estado, código postal y país.
• /v1/geo/distance calcula la distancia del círculo máximo entre dos puntos usando la fórmula de Haversine. Devuelve tanto km como millas.
• El acceso anónimo permite 5 solicitudes por minuto y 100 por día. No se requiere clave API para pruebas o uso de bajo volumen.
• Los tres puntos finales aceptan y devuelven JSON. Sin codificación de cadena de consulta, sin análisis XML, sin Instalación del SDK. Cualquier idioma con un cliente HTTP funciona.