التوثيق

كل شيء هو طلب GET إلى https://api.mygeocode.com/v1/ مع معاملات استعلام، والرد يكون بصيغة JSON. تغطي هذه الصفحة الأجزاء المشتركة بين جميع نقاط النهاية. أما صفحات نقاط النهاية فتغطي معاملات كل منها وحقولها.

طلبك الأول

لا حاجة إلى مفتاح لأول 2,500 طلب يوميًا من العنوان الواحد. من أي جهاز:

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

احتُسب ذلك الطلب بوصفه الطلب 1 من أصل 2,500 طلب مجاني يحصل عليها عنوانك اليوم. ولو استُخدم مفتاح لاحتُسب على المفتاح بدلًا من ذلك، ولأضافت الترويسات أرقام رصيدك وخانات IP. تخبرك ترويسات الاستجابة بموقفك:

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-free-remaining: 2499
x-quota-reset: 1756339200
x-request-id: 2726386e38428697

هل أنت قادم من مزوّد آخر؟

قد لا تحتاج إلى بقية هذه الصفحة. إذا كان كودك يتعامل بالفعل مع Google Maps أو Bing Maps أو HERE أو Mapbox أو Geocode.Farm أو Nominatim أو OpenCage أو LocationIQ أو Geoapify أو TomTom أو MapQuest أو Geocodio أو PositionStack أو ip-api أو ipinfo أو ipstack أو Open-Elevation، فنحن نشغّل مضيفًا يتحدث بصيغة الطلب والاستجابة الخاصة بذلك المزوّد وخلفه بياناتنا. غيّر اسم المضيف، وضع مفتاحك حيث كان المفتاح القديم، واحتفظ بكود التحليل لديك. وينطبق الأمر نفسه على Google Maps JavaScript API وBing Maps V8 وHERE Maps for JavaScript وMapQuest.js، وإضافات الترميز الجغرافي في MapLibre وMapbox GL وLeaflet.

كيف تعمل المضيفات البديلة المتوافقة: مصفوفة المضيفات الكاملة، وربط المفاتيح، وربط الأخطاء، وقائمة تحقق للانتقال.

عنوان URL الأساسي ونقاط النهاية

نقطة النهاية	المسار	المعاملات المطلوبة
الترميز الجغرافي الأمامي	`GET /v1/forward`	`q` (أو حقول منظَّمة)
الترميز الجغرافي العكسي	`GET /v1/reverse`	`lat`, `lon`
الإكمال التلقائي للعناوين	`GET /v1/autocomplete`	`q`
الاستعلام عن IPv4	`GET /v1/ipv4`	لا شيء (`ip` اختياري)
الاستعلام عن IPv6	`GET /v1/ipv6`	لا شيء (`ip` اختياري)
الاستعلام عن IP، بأي من الإصدارين	`GET /v1/ip`	لا شيء (`ip` اختياري)
الاستعلام عن المنطقة الزمنية	`GET /v1/timezone`	`lat`, `lon`
الاستعلام عن الارتفاع	`GET /v1/elevation`	`lat` و`lon` أو `locations`
الاستعلام عن الرمز البريدي	`GET /v1/postcode`	`code`

لا نخدم إلا عبر HTTPS. تُرفض طلبات HTTP العادية بالرمز 400 بدلًا من إعادة توجيهها، حتى لا يُرسل مفتاح دون تشفير عن طريق الخطأ. يدعم الخادم HTTP/2 وHTTP/3. تُضغط الاستجابات عندما يقبل العميل gzip أو br.

غلاف الاستجابة

كل استجابة هي كائن JSON يحتوي على status قيمته ok أو error.

عند ok تتبعه البيانات: results (مصفوفة) لنقاط النهاية التي قد تعيد عدة تطابقات، وresult (كائن أو null) للترميز الجغرافي العكسي، وحقول مسطّحة لعمليات الاستعلام عن IP والمنطقة الزمنية.
عند error يوجد كائن error يحتوي على سلسلة code وجملة message، وعند الحاجة المعامل param الذي تسبب في الخطأ. ويتطابق رمز حالة HTTP معه. راجع الأخطاء.

الاستعلام الصالح الذي لا يطابق شيئًا يكون ok مع مصفوفة results فارغة أو result قيمته null. هذا ليس خطأ، ويُحتسب طلبًا.

معاملات تقبلها جميع نقاط النهاية

المعامل	الوصف
`key`	مفتاح API الخاص بك، إذا كنت تفضّل معامل استعلام على الترويسة `X-API-Key`. الترويسة أفضل لأن سلاسل الاستعلام ينتهي بها المطاف في السجلات.
`lang`	رمز لغة ISO 639-1 لأسماء الأماكن، حيثما توفرت لدينا. القيمة الافتراضية `en`. تنسيق العنوان يتبع دائمًا عرف الدولة.
`pretty`	`1` لإضافة مسافات بادئة إلى JSON. مفيد في المتصفح، واتركه في الكود.

أسماء المعاملات حساسة لحالة الأحرف وتُكتب بأحرف صغيرة. تُتجاهل المعاملات غير المعروفة، وتُعامل المعاملات الفارغة كأنها غير موجودة، لذا يمكن لنموذج HTML أن يرسل الحقول الاختيارية فارغة. الإحداثيات بالدرجات العشرية: lat من -90 إلى 90 وlon من -180 إلى 180. النص بترميز UTF-8 وينبغي ترميزه لعنوان URL.

المصادقة في فقرة واحدة

المفتاح اختياري: يحصل كل عنوان على 2,500 طلب مجاني يوميًا دون مفتاح. يُرسل المفتاح في الترويسة X-API-Key أو رمز Authorization: Bearer أو المعامل key. المفاتيح مجانية، ويتطلب الحساب اسمك وعنوان بريد إلكتروني وكلمة مرور. لكل مفتاح 2,500 طلب مجاني يوميًا خاصة به، وبعدها تستهلك الطلبات الرصيد المسبق الدفع للحساب بسعر 0.0001 € للطلب الواحد، أو تكون مجانية على مفتاح ينتمي إلى باقة Unlimited (50 € شهريًا). تتشارك الطلبات دون مفتاح والطلبات بمفتاح من الشبكة نفسها حصة يومية واحدة. يعمل مفتاح الدفع حسب الاستخدام من عنوانَي IP في كل 24 ساعة متجددة، ومفتاح Unlimited من ثلاثة. القواعد الكاملة في صفحة المصادقة.

ترويسات الحصة

الترويسة	المعنى
`X-Quota-Limit`	الطلبات المجانية يوميًا لهذا المفتاح، أو لهذا العنوان إذا لم يُرسل مفتاح: 2,500. على مفتاح Unlimited تكون `-1`.
`X-Quota-Used`	الطلبات المحتسبة على هذا المفتاح اليوم، بما فيها هذا الطلب.
`X-Quota-Free-Remaining`	الطلبات المجانية المتبقية على هذا المفتاح اليوم. `-1` على مفتاح Unlimited.
`X-Credits-Remaining`	عدد الطلبات المدفوعة الإضافية التي يغطيها رصيد الحساب.
`X-Key-IPs-Used`, `X-Key-IPs-Limit`	خانات IP المشغولة على هذا المفتاح الآن، وعدد الخانات التي يملكها.
`X-Quota-Reset`	توقيت Unix للساعة 00:00 UTC التالية، حين تُصفَّر العدادات اليومية.
`X-Request-Id`	معرّف فريد للطلب. اذكره عند مراسلة الدعم.

الاستدعاء من المتصفحات

CORS مفعّل على كل نقطة نهاية وترويسات الحصة مكشوفة، لكن المفتاح الموجود في مصدر الصفحة علني وستُستنفد خانات IP الخاصة به بعد زائرين أو ثلاثة. نفّذ الاستدعاءات من خادمك، وراجع المفاتيح والمتصفحات.

إدارة الإصدارات

بادئة المسار /v1/ هي الإصدار. ضمن الإصدار الواحد نضيف حقولًا ومعاملات لكننا لا نحذفها ولا نعيد تسميتها أبدًا، ولا نغيّر معنى حقل موجود. إذا احتجنا يومًا إلى كسر التوافق في شيء ما، فسيكون ذلك في /v2/ وسيستمر /v1/ في العمل لمدة ستة أشهر على الأقل بعد الإعلان. تُعلن الإضافات في قسم الأخبار في المدونة.

يجب أن يتجاهل محلل JSON لديك الحقول التي لا يعرفها. هذا هو الشرط الوحيد للتوافق المستقبلي.