API de geocodificação gratuita: avanço, reversão e distância em uma chamada REST

Seu aplicativo de entrega precisa converter um endereço em latitude e longitude para roteamento. A API de geocodificação do Google Maps custa US$ 5 por 1.000 solicitações. Para uma startup fazendo 10.000 entregas por dia, isso equivale a US$ 50/dia apenas em geocodificação.

A API botoi geo cobre geocodificação direta, geocodificação reversa e cálculo de distância com três pontos de extremidade REST. O acesso anônimo atende 100 solicitações por dia sem nenhum custo. Planos pagos comece em US$ 9/mês e cubra todos os mais de 150 endpoints da plataforma, não apenas a geocodificação.

Geocodificação direta: endereço para coordenadas

O /v1/geo/geocode endpoint pega um endereço e retorna latitude, longitude e um endereço formatado padronizado. Uma solicitação POST:

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

Resposta:

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

A resposta inclui o código do país, o nome do local (quando disponível) e um formatted_address string que você pode armazenar como a versão canônica. Parcial endereços também funcionam; a API resolve "Mountain View, CA" para as coordenadas do centro da cidade.

Geocodificação reversa: coordenadas para endereço

Um aplicativo móvel captura uma queda de pino GPS. Você precisa de um endereço legível para o recibo. O /v1/geo/reverse ponto final pega latitude e longitude e quebra o resultado em componentes estruturados:

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

Resposta:

{
  "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 é separado: rua, número da casa, cidade, estado, código postal e país. Você não precisa analisar uma única string para extrair a cidade ou o CEP.

Cálculo da distância entre dois pontos

O /v1/geo/distance ponto final calcula a distância do grande círculo entre dois pares de coordenadas. Ele retorna quilômetros e milhas:

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

Resposta:

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

São Francisco a Los Angeles: 559 km. O cálculo utiliza a fórmula Haversine, que fornece uma distância em linha reta através da superfície da Terra. Para filtros de proximidade, entrega verificações de raio e recursos de localização de lojas, esta é a métrica correta.

Exemplo prático: validação de endereço no checkout

Um cliente digita “123 Fake Stret, Nowhereville” em seu formulário de checkout. Validação de sintaxe passa porque parece um endereço. A geocodificação detecta o problema. Se a API não puder resolver o endereço em coordenadas, o endereço provavelmente será inválido.

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

Essa abordagem detecta erros de digitação, nomes de ruas inexistentes e endereços incompletos antes que você enviar um pacote para lugar nenhum. O formatted_address campo fornece a você o versão padronizada para armazenar em seu banco de dados.

Exemplo prático: localizador de lojas

Dadas as coordenadas de um usuário (da geolocalização do navegador ou de um endereço geocodificado), encontre os três lojas mais próximas:

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 um pequeno número de lojas (menos de 50), as chamadas paralelas de API funcionam bem. Por centenas de locais, faça o cálculo de Haversine no lado do cliente e use a API apenas para a geocodificação passo.

Exemplo prático: verificação do raio de entrega

Um aplicativo de entrega de comida precisa rejeitar pedidos fora de um raio de 25 km da cozinha. Verifique a distância antes de aceitar o 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.\`
  );
}

A verificação realiza uma chamada de API e retorna em menos de 100 ms. Combine-o com geocodificação direta passar de um endereço digitado para uma decisão de elegibilidade de entrega em duas solicitações sequenciais.

Pontos-chave

• /v1/geo/geocode converte endereços de ruas em latitude/longitude com um endereço formatado padronizado. Funciona com endereços parciais e nomes de lugares.
• /v1/geo/reverse converte coordenadas em um endereço estruturado com separado campos para rua, cidade, estado, código postal e país.
• /v1/geo/distance calcula a distância do grande círculo entre dois pontos usando a fórmula de Haversine. Retorna km e milhas.
• O acesso anônimo permite 5 solicitações por minuto e 100 por dia. Nenhuma chave de API necessária para testes ou uso de baixo volume.
• Todos os três endpoints aceitam e retornam JSON. Sem codificação de string de consulta, sem análise de XML, sem Instalação do SDK. Qualquer linguagem com um cliente HTTP funciona.