無料のジオコーディング API: 1 回の REST 呼び出しで順方向、逆方向、距離を実行

配送アプリは、ルーティングのために住所を緯度と経度に変換する必要があります。 Google Maps Geocoding API の料金は 1,000 リクエストあたり 5 ドルです。 10,000 件の配達を行うスタートアップの場合 ジオコーディングだけで 1 日あたり 50 ドルになります。

Botoi Geo API は、順方向ジオコーディング、逆方向ジオコーディング、および距離計算をカバーします。 3 つの REST エンドポイント。 匿名アクセスは、1 日あたり 100 件のリクエストを無料で処理します。 有料プラン 月額 9 ドルから始まり、ジオコーディングだけではなく、プラットフォーム内の 150 以上のエンドポイントすべてをカバーします。

フォワードジオコーディング: 住所から座標へ

の /v1/geo/geocode エンドポイントは住所を取得して緯度を返します。 経度、および標準化された形式の住所。 1 つの 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"
  }
}

番地、番地、都市、州、郵便番号、国など、すべてのフィールドが分​​離されています。 都市番号や郵便番号を抽出するために単一の文字列を解析する必要はありません。

2点間の距離計算

の /v1/geo/distance エンドポイントは、間の大圏距離を計算します。 2 つの座標ペア。 キロメートルとマイルの両方を返します。

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 km。 計算にはハバーサイン公式が使用されます。 地球の表面を横切る直線距離を示します。 近接フィルタの場合、配送 半径チェック、およびストア ロケーター機能の場合、これは正しいメトリックです。

実践例: チェックアウト時の住所検証

顧客がチェックアウト フォームに「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 フィールドが提供するのは、 データベースに保存する標準化されたバージョン。

実践例: 店舗検索

ユーザーの座標 (ブラウザーの地理位置情報または地理コード化された住所から) を指定して、3 つの座標を見つけます。 最寄りの店舗:

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 呼び出しは適切に機能します。 何百もの 場所の場合、クライアント側でハバーサイン計算を実行し、ジオコーディングのみに API を使用します。 ステップ。

実践例：配送範囲チェック

食品配達アプリは、キッチンから半径 25 km の範囲外の注文を拒否する必要があります。 チェックする 注文を受け入れるまでの距離:

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

チェックは 1 回の API 呼び出しで完了し、100 ミリ秒以内に戻ります。 フォワードジオコーディングと組み合わせる 入力されたアドレスから配送適格性の決定まで、2 つの連続したリクエストで行われます。

重要なポイント

• /v1/geo/geocode を使用して番地を緯度/経度に変換します。 標準化された形式のアドレス。 部分的な住所と場所名を処理します。
• /v1/geo/reverse 座標を別個の構造化アドレスに変換します。 番地、都市、州、郵便番号、および国のフィールド。
• /v1/geo/distance 次を使用して 2 点間の大圏距離を計算します ハバーシン式。 km とマイルの両方を返します。
• 匿名アクセスでは、1 分あたり 5 件、1 日あたり 100 件のリクエストが許可されます。 API キーは必要ありません テストまたは少量の使用。
• 3 つのエンドポイントはすべて JSON を受け入れて返します。 クエリ文字列エンコーディング、XML 解析なし、 SDKのインストール。 HTTP クライアントを備えたあらゆる言語が機能します。