المصادقة

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

دون مفتاح

أرسل الطلب دون أي بيانات اعتماد على الإطلاق وستتلقى الرد. يحصل كل عنوان على 2,500 طلب يوميًا بهذه الطريقة، تُحتسب بدءًا من 00:00 UTC عبر كل نقطة نهاية وكل مضيف بديل متوافق، مع البيانات نفسها والإجابات نفسها التي يحصل عليها الحساب المدفوع. بعد ذلك يرد API بالرمز 429 quota_exceeded مع ترويسة Retry-After حتى إعادة التصفير، ولا يُفرض أي رسم ولا يوضع أي طلب في قائمة انتظار.

أمران يجب معرفتهما. العناوين التي تنتمي إلى الشبكة نفسها تتشارك حصة واحدة، لذا قد يستنفدها مكتب مزدحم أو حرم جامعي أو منطقة سحابية واحدة أسرع مما يفعله جهاز منفرد. كما أن الشبكة والمفاتيح المستخدمة منها تستهلك الحصة نفسها: الطلبات المرسلة دون مفتاح تقلّل ما يحصل عليه اليوم مفتاح مستخدم من تلك الشبكة، والطلبات المجانية المرسلة بذلك المفتاح تقلّل ما تحصل عليه الشبكة دون مفتاح. لذلك يضيف إنشاء حساب الرصيد والباقات والسجل، لا 2,500 مجانية ثانية من المكان نفسه.

الحصول على مفتاح

أنشئ حسابًا على www.mygeocode.com/signup باسمك وعنوان بريد إلكتروني وكلمة مرور. يُعرض مفتاحك الأول مرة واحدة فقط في الحال، فانسخه، لأننا لا نخزّن إلا قيمة التجزئة. أنشئ ما تشاء من المفاتيح الإضافية ضمن مفاتيح API، وأعطِ كل مفتاح تسمية (مفتاح لكل خادم أو لكل تطبيق عادة جيدة)، وألغِ أيًا منها في أي وقت.

لكل مفتاح 2,500 طلب مجاني يوميًا، تُحتسب بدءًا من 00:00 UTC عبر كل نقطة نهاية وكل مضيف بديل متوافق. بعد ذلك تستهلك الطلبات الرصيد المسبق الدفع للحساب بسعر 0.0001 € للطلب الواحد، ما لم يكن المفتاح ينتمي إلى باقة Unlimited.

إرسال المفتاح

أي من هذه الطرق يعمل على كل مضيف. فضّل الترويسة: سلاسل الاستعلام ينتهي بها المطاف في سجلات الخوادم وسجلات المتصفحات والوكلاء.

$ curl -H "X-API-Key: mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl -H "Authorization: Bearer mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12&key=mg_7f3c2a19e04b...d1"

$ curl -u "mg_7f3c2a19e04b...d1:" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

على المضيفات البديلة المتوافقة يوضع المفتاح أيضًا حيث كان يوضع مفتاح المزوّد الأصلي: key لدى Google وBing وGeocode.Farm وOpenCage وLocationIQ وTomTom وMapQuest، وapiKey لدى HERE وGeoapify، وaccess_token لدى Mapbox، وapi_key لدى Geocodio، وaccess_key لدى PositionStack وipstack، وtoken لدى ipinfo. يضيف عملاء Nominatim وOpen-Elevation المعامل key= أو ترويسة، لأن هاتين الخدمتين ليس لهما مفتاح خاص.

إلى جانب معامل الاستعلام، تُقبل أربع طرق لإرسال بيانات الاعتماد على كل مضيف، لذا لا تحتاج مكتبة العميل التي تصادق بطريقة المزوّد إلى أي تغيير: الترويسة X-API-Key، وAuthorization: Bearer، ومصادقة HTTP Basic مع المفتاح بوصفه اسم المستخدم (وهو ما يرسله curl -u KEY: وما تستخدمه أمثلة ipinfo)، والترويسة X-Goog-Api-Key التي ترسلها عملاء Google. ويُقرأ المفتاح في جسم النموذج أيضًا، لنقاط النهاية التي تُرسل إليها البيانات بطريقة POST. تغيير اسم المضيف والمفتاح هو كل ما يتطلبه الانتقال.

نوعان من المفاتيح

خانات IP

يمكن استخدام المفتاح من عدد محدود من عناوين IP في الوقت نفسه: عنوانان لمفتاح الدفع حسب الاستخدام، وثلاثة لمفتاح Unlimited. القاعدة متجددة، لكل عنوان على حدة:

• في أول مرة يستخدم فيها عنوان المفتاح يشغل خانة، ويحتفظ بها لمدة 24 ساعة من ذلك الطلب الأول.
• عند انقضاء تلك المدة البالغة 24 ساعة تتحرر الخانة تلقائيًا، أيًا كان ما تفعله العناوين الأخرى. وإذا عاد العنوان نفسه لاحقًا فإنه يشغل خانة من جديد ببساطة.
• الطلب من عنوان جديد بينما جميع الخانات مشغولة يُرفض بالرمز 403 والرمز key_ip_limit. توضح الرسالة موعد تحرر الخانة التالية. لا تُحتسب الطلبات المرفوضة.

فإذا استخدم خادمان مفتاحًا لأول مرة في 02:00 وخادم ثالث في 04:00، تتحرر خانتان في 02:00 من اليوم التالي والثالثة في 04:00. تعرض لوحة التحكم العناوين التي تشغل خانات المفتاح وموعد تحرر كل منها. هل تحتاج إلى أجهزة أكثر؟ أنشئ مزيدًا من مفاتيح الدفع حسب الاستخدام، أو أضف مزيدًا من باقات Unlimited، فكل باقة تأتي بمفتاحها الخاص.

وُجد هذا الحد لأن المفاتيح تتسرّب. بفضله، يصبح المفتاح الذي ينتهي به المطاف في مستودع عام قليل القيمة لمن يعثر عليه، وبما أن الرصيد مسبق الدفع فلا يمكن لأحد أن ينفق أكثر من الرصيد الذي شحنته.

المفاتيح والمتصفحات

لا تضع مفتاحًا في JavaScript أو في تطبيق جوال. يستطيع أي شخص قراءته من الصفحة، وكل زائر هو عنوان IP جديد، لذا تنفد خانات المفتاح بعد الزائر الثاني أو الثالث. استدعِ API من خادمك واحتفظ بالمفتاح هناك. تحمّل بدائل خرائط JavaScript المتوافقة البلاطات والمكتبات دون مفتاح، ولا يلزم أن يمر عبر خادمك سوى استدعاءات الترميز الجغرافي فيها.

الإلغاء والتدوير

ألغِ مفتاحًا من لوحة التحكم وسيتوقف عن العمل خلال دقيقة. أنشئ المفتاح الجديد أولًا، وانشره، ثم ألغِ القديم، فكلاهما يعمل في الأثناء. لا تنتهي صلاحية المفاتيح من تلقاء نفسها أبدًا.

حالات الرفض

لا يُحتسب أي من هذه على الحصة ولا يكلّف رصيدًا. على المضيفات البديلة المتوافقة يُبلّغ عنها بشكل المزوّد الأصلي، راجع التوافق.