Бесплатный API геокодирования: вперед, назад и расстояние за один вызов REST

Вашему приложению доставки необходимо преобразовать адрес в широту и долготу для маршрутизации. API геокодирования Google Maps стоит 5 долларов США за 1000 запросов. Для стартапа, делающего 10 000 доставок в день это 50 долларов в день только за геокодирование.

API botoi geo охватывает прямое геокодирование, обратное геокодирование и расчет расстояния с помощью три конечных точки REST. Анонимный доступ обрабатывает 100 запросов в день бесплатно. Платные планы начните с 9 долларов США в месяц и охватывайте все более 150 конечных точек на платформе, а не только геокодирование.

Прямое геокодирование: адрес к координатам

The /v1/geo/geocode конечная точка принимает адрес и возвращает широту, долгота и стандартизированный адрес. Один POST-запрос:

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

Ответ:

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

Ответ включает код страны, название места (если оно доступно) и formatted_address строку, которую вы можете сохранить как каноническую версию. Частичный адреса тоже работают; API преобразует «Маунтин-Вью, Калифорния» в координаты центра города.

Обратное геокодирование: координаты по адресу

Мобильное приложение фиксирует падение булавки GPS. Для получения вам понадобится удобочитаемый адрес. /v1/geo/reverse конечная точка принимает широту и долготу и разрывает результат на структурированные компоненты:

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

Ответ:

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

Каждое поле разделено: улица, номер дома, город, штат, почтовый индекс и страна. Вам не нужно анализировать ни одну строку, чтобы извлечь город или почтовый индекс.

Расчет расстояния между двумя точками

The /v1/geo/distance конечная точка вычисляет расстояние по большому кругу между две пары координат. Он возвращает как километры, так и мили:

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

Ответ:

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

Сан-Франциско — Лос-Анджелес: 559 км. В расчете используется формула Хаверсинуса, которая дает вам расстояние по прямой линии по поверхности Земли. Для бесконтактных фильтров, доставка проверки радиуса и функции локатора магазинов — это правильный показатель.

Практический пример: проверка адреса при оформлении заказа

Клиент вводит «123 Fake Stret, Nowhereville» в форму оформления заказа. Проверка синтаксиса проходит, потому что это похоже на адрес. Геокодирование решает проблему. Если API не может разрешить адрес в координатах, адрес, скорее всего, недействителен.

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

Этот подход выявляет опечатки, несуществующие названия улиц и неполные адреса, прежде чем вы отправить посылку в никуда. formatted_address поле дает вам стандартизированная версия для хранения в вашей базе данных.

Практический пример: расположение магазинов

Учитывая координаты пользователя (из геолокации браузера или геокодированного адреса), найдите три ближайшие магазины:

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

Для небольшого количества магазинов (до 50) хорошо работают параллельные вызовы API. Для сотен местоположения, выполните расчет Haversine на стороне клиента и используйте API только для геокодирования. шаг.

Практический пример: проверка радиуса доставки

Приложение для доставки еды должно отклонять заказы в радиусе 25 км от кухни. Проверить расстояние до принятия заказа:

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

Проверка принимает один вызов API и возвращает результат менее чем за 100 мс. Объедините это с прямым геокодированием перейти от введенного адреса к решению о приемлемости доставки в двух последовательных запросах.

Ключевые моменты

• /v1/geo/geocode преобразует уличные адреса в широту/долготу с помощью стандартизированный форматированный адрес. Работает с частичными адресами и географическими названиями.
• /v1/geo/reverse преобразует координаты в структурированный адрес с отдельными поля для улицы, города, штата, почтового индекса и страны.
• /v1/geo/distance вычисляет расстояние по большому кругу между двумя точками, используя формула Гаверсина. Возвращает как км, так и мили.
• Анонимный доступ допускает 5 запросов в минуту и ​​100 в день. Ключ API не требуется для тестирование или использование в небольших объемах.
• Все три конечные точки принимают и возвращают JSON. Никакого кодирования строки запроса, никакого синтаксического анализа XML, никакого Установка SDK. Любой язык с HTTP-клиентом работает.