API geocoding gratis: maju, mundur, dan jarak dalam satu panggilan REST

Aplikasi pengiriman Anda perlu mengubah alamat jalan menjadi garis lintang dan garis bujur untuk perutean. Google Maps Geocoding API berharga $5 per 1.000 permintaan. Untuk startup yang melakukan 10.000 pengiriman sehari, itu $50/hari untuk geocoding saja.

Botoi geo API mencakup geocoding maju, geocoding terbalik, dan penghitungan jarak tiga titik akhir REST. Akses anonim menangani 100 permintaan per hari tanpa biaya. Paket berbayar mulai dari $9/bulan dan mencakup 150+ titik akhir di platform, bukan hanya geocoding saja.

Meneruskan geocoding: alamat ke koordinat

Itu /v1/geo/geocode titik akhir mengambil alamat jalan dan mengembalikan garis lintang, bujur, dan alamat berformat standar. Satu permintaan POST:

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

Tanggapan:

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

Responsnya mencakup kode negara, nama tempat (bila tersedia), dan a formatted_address string yang dapat Anda simpan sebagai versi kanonik. Sebagian alamat juga berfungsi; API menyelesaikan "Mountain View, CA" menjadi koordinat pusat kota.

Geocoding terbalik: koordinat ke alamat

Aplikasi seluler menangkap pin drop GPS. Anda memerlukan alamat yang dapat dibaca manusia untuk tanda terima. Itu /v1/geo/reverse titik akhir mengambil garis lintang dan garis bujur dan memecahnya hasil menjadi komponen terstruktur:

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

Tanggapan:

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

Setiap bidang dipisahkan: jalan, nomor rumah, kota, negara bagian, kode pos, dan negara. Anda tidak perlu mengurai satu string pun untuk mengekstrak kota atau kode pos.

Perhitungan jarak antara dua titik

Itu /v1/geo/distance titik akhir menghitung jarak lingkaran besar antara dua pasangan koordinat. Ia mengembalikan kilometer dan mil:

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

Tanggapan:

{
  "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 ke Los Angeles: 559 km. Perhitungannya menggunakan rumus Haversine yaitu memberi Anda jarak garis lurus melintasi permukaan bumi. Untuk filter kedekatan, pengiriman pemeriksaan radius, dan fitur pencari lokasi toko, ini adalah metrik yang tepat.

Contoh praktis: validasi alamat saat checkout

Seorang pelanggan mengetik "123 Fake Stret, Nowhereville" ke dalam formulir pembayaran Anda. Validasi sintaksis lolos karena terlihat seperti alamat. Geocoding menangkap masalahnya. Jika API tidak bisa selesaikan alamat ke koordinat, kemungkinan besar alamat tersebut tidak valid.

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

Pendekatan ini menangkap kesalahan ketik, nama jalan yang tidak ada, dan alamat yang tidak lengkap sebelum Anda mengirimkan paket ke mana pun. Itu formatted_address bidang memberi Anda versi standar untuk disimpan di database Anda.

Contoh praktis: pencari lokasi toko

Berdasarkan koordinat pengguna (dari geolokasi browser atau alamat geocode), temukan ketiganya toko terdekat:

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

Untuk sejumlah kecil toko (di bawah 50), panggilan API paralel berfungsi dengan baik. Untuk ratusan lokasi, lakukan penghitungan Haversine di sisi klien dan gunakan API hanya untuk geocoding langkah.

Contoh praktis: pemeriksaan radius pengiriman

Aplikasi pesan-antar makanan harus menolak pesanan di luar radius 25 km dari dapur. Periksa jarak sebelum menerima pesanan:

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

Pemeriksaan ini memerlukan satu panggilan API dan kembali dalam waktu kurang dari 100 md. Gabungkan dengan geocoding maju untuk beralih dari alamat yang diketik ke keputusan kelayakan pengiriman dalam dua permintaan berurutan.

Poin-poin penting

• /v1/geo/geocode mengubah alamat jalan menjadi lintang/bujur dengan a alamat berformat standar. Bekerja dengan sebagian alamat dan nama tempat.
• /v1/geo/reverse mengubah koordinat menjadi alamat terstruktur dengan terpisah bidang untuk jalan, kota, negara bagian, kode pos, dan negara.
• /v1/geo/distance menghitung jarak lingkaran besar antara dua titik menggunakan rumus Haversine. Mengembalikan km dan mil.
• Akses anonim memungkinkan 5 permintaan per menit dan 100 per hari. Tidak diperlukan kunci API untuk pengujian atau penggunaan volume rendah.
• Ketiga titik akhir menerima dan mengembalikan JSON. Tidak ada pengkodean string kueri, tidak ada penguraian XML, tidak Instalasi SDK. Bahasa apa pun dengan klien HTTP berfungsi.