واجهة برمجة تطبيقات الترميز الجغرافي المجانية: للأمام والخلف والمسافة في مكالمة REST واحدة

يحتاج تطبيق التسليم الخاص بك إلى تحويل عنوان الشارع إلى خطوط الطول والعرض للتوجيه. تبلغ تكلفة واجهة برمجة تطبيقات الترميز الجغرافي لخرائط Google 5 دولارات لكل 1000 طلب. لشركة ناشئة تقوم بـ 10,000 عملية تسليم في اليوم، هذا يعني 50 دولارًا في اليوم على الترميز الجغرافي وحده.

تغطي واجهة برمجة تطبيقات botoi Geo الترميز الجغرافي الأمامي والترميز الجغرافي العكسي وحساب المسافة ثلاث نقاط نهاية REST. يتعامل الوصول المجهول مع 100 طلب يوميًا دون أي تكلفة. الخطط المدفوعة ابدأ بسعر 9 دولارات شهريًا وقم بتغطية جميع نقاط النهاية التي يزيد عددها عن 150 نقطة في النظام الأساسي، وليس الترميز الجغرافي وحده.

الترميز الجغرافي إلى الأمام: عنوان الإحداثيات

ال /v1/geo/geocode تأخذ نقطة النهاية عنوان الشارع وترجع خط العرض، خط الطول، وعنوان منسق موحد. طلب مشاركة واحدة:

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

يتضمن الرد رمز البلد واسم المكان (عند توفره) وa formatted_address سلسلة يمكنك تخزينها كإصدار أساسي. جزئي العناوين تعمل أيضًا؛ تقوم واجهة برمجة التطبيقات (API) بتحليل "Mountain View، CA" لإحداثيات وسط المدينة.

عكس الترميز الجغرافي: إحداثيات العنوان

يلتقط تطبيق الهاتف المحمول قطرة دبوس 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"
  }
}

يتم فصل كل حقل: الشارع، رقم المنزل، المدينة، الولاية، الرمز البريدي، والبلد. لا تحتاج إلى تحليل سلسلة واحدة لاستخراج المدينة أو الرمز البريدي.

حساب المسافة بين نقطتين

ال /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 كم. يستخدم الحساب صيغة Haversine، والتي يمنحك مسافة خط مستقيم عبر سطح الأرض. لمرشحات القرب، والتسليم عمليات التحقق من نصف القطر وميزات تحديد موقع المتجر، هذا هو المقياس الصحيح.

مثال عملي: التحقق من صحة العنوان عند الخروج

يقوم العميل بكتابة "123 Fake Stret, Nowhereville" في نموذج الدفع الخاص بك. التحقق من صحة بناء الجملة يمر لأنه يبدو وكأنه عنوان. يلتقط الترميز الجغرافي المشكلة. إذا لم تتمكن واجهة برمجة التطبيقات من ذلك قم بتحويل العنوان إلى الإحداثيات، فمن المحتمل أن يكون العنوان غير صالح.

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)، تعمل مكالمات واجهة برمجة التطبيقات المتوازية بشكل جيد. لمئات من المواقع، قم بإجراء حساب 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.