الحصص والرصيد والحدود

يحصل كل مفتاح على حصة يومية مجانية. بعدها تستهلك الطلبات الرصيد المسبق الدفع أو تغطيها باقة Unlimited. تخبرك كل استجابة بموقفك في ترويساتها.

الحصة اليومية

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

ما الذي يُحتسب طلبًا

• كل استدعاء ناجح (200) إلى أي نقطة نهاية يُحتسب طلبًا واحدًا، سواء وجد شيئًا أم لا.
• كل عنصر في استدعاء مجمّع يُحتسب طلبًا واحدًا: كل عنوان في دفعة IP، وكل نقطة في استدعاء ارتفاع أو منطقة زمنية متعدد النقاط، وكل إدخال في نقاط النهاية المجمّعة على المضيفات البديلة المتوافقة. وهكذا يحتسبها المزوّدون الأصليون أيضًا. الدفعة الأكبر مما تبقى من الحصة تُرفض كاملة، قبل أي معالجة، بخطأ الحد الخاص بالمزوّد نفسه بدلًا من الإجابة عن جزء منها. يقبل كل مضيف في الاستدعاء الواحد عدد العناصر نفسه الذي يقبله مزوّده الأصلي (100 لدى ip-api وMapQuest، و50 لدى ipstack، و512 لارتفاعات Google، و1,000 لدى ipinfo وMapbox وGeoapify، و1,024 لدى Bing وOpen-Elevation، و10,000 لدى Geocodio والدفعة غير المتزامنة في TomTom، و100 على نقاط النهاية الأصلية لدينا). جلب نتيجة غير متزامنة مخزّنة لا يُحتسب إطلاقًا.
• الاستدعاءات المرفوضة بالرمز 400 أو 401 أو 402 أو 403 أو 404 لا تُحتسب ولا تكلّف شيئًا.
• الاستدعاءات التي تفشل بالرمز 500 أو 503 لا تُحتسب ولا تكلّف شيئًا.
• بلاطات الخرائط وملفات JSON للأنماط وتحميل المكتبات من بدائل JavaScript المتوافقة لا تُحتسب.

خانات IP

يعمل المفتاح من عنوانَي IP في الوقت نفسه (ثلاثة لمفتاح Unlimited). يحتفظ كل عنوان بخانته لمدة 24 ساعة من طلبه الأول ثم يحررها. الطلب من عنوان إضافي بينما جميع الخانات مشغولة يتلقى 403 key_ip_limit مع موعد تحرر الخانة التالية. التفاصيل والأمثلة في صفحة المصادقة.

الدفقات

لا يوجد اليوم حد ثابت لعدد الطلبات في الثانية، بمفتاح أو دونه. حركة المرور التي تبدو كحلقة خارجة عن السيطرة أو كهجوم قد تُبطَّأ، وسنخبرك إن حدث ذلك لأحد مفاتيحك. إذا كان لديك عمل كبير، فاستخدم صيغ الدفعات (ips وlocations) بدلًا من آلاف الاستدعاءات المنفردة.

قراءة الترويسات

x-quota-limit: 2500          # free per day for this key; -1 on an Unlimited key
x-quota-used: 2431           # counted today on this key, including this request
x-quota-free-remaining: 69   # free requests left today on this key
x-credits-remaining: 148200  # requests the account's credit still covers
x-key-ips-used: 1            # IP slots currently held on this key
x-key-ips-limit: 2           # slots on this key
x-quota-reset: 1789948800    # Unix time of the next 00:00 UTC
x-request-id: 2726386e38428697

التعامل مع 402 و403

{ "status": "error", "error": { "code": "no_credits", "message": "The free allowance of 2500 requests for today is used and the account balance (€0.0000, 0 requests) does not cover this request. Add credit at https://www.mygeocode.com/dashboard or wait for the reset at 00:00 UTC." } }

لا تُعد المحاولة في حلقة، فالإجابة ستبقى نفسها حتى يُضاف رصيد أو يُعاد تصفير اليوم. اقرأ X-Quota-Reset ثم إما أن تنتظر، أو تُفشل العملية وتخبر المستخدم، أو تشحن الرصيد. ترسل لك لوحة التحكم بريدًا إلكترونيًا عندما يقترب الرصيد من النفاد.

{ "status": "error", "error": { "code": "key_ip_limit", "message": "This key is already in use from 2 IP addresses in the last 24 hours (limit 2). The next slot frees at 2026-09-21 23:06 UTC. Use another key or an additional Unlimited package for more addresses." } }

يعني هذا أن جهازًا ليس من الأجهزة التي تشغل خانات المفتاح حاليًا حاول استخدامه. عادةً يكون ذلك خادمًا جديدًا أو إعادة نشر بعنوان جديد، فامنح ذلك الجهاز مفتاحه الخاص.

تقليل الطلبات

يمكنك تخزين النتائج مؤقتًا إلى أجل غير مسمى، فافعل ذلك. العناوين لا تتحرك، والترميز الجغرافي الأمامي نفسه غدًا يعطي الإجابة نفسها. نطاقات IP تتغير ببطء، ويوم واحد مدة تخزين مؤقت آمنة. قواعد المنطقة الزمنية لنقطة ما نادرًا ما تتغير، واسم IANA لا يتغير عمليًا أبدًا. في الإكمال التلقائي، أخّر معالجة الإدخال بنحو 150 ms وتوقف عن الإرسال بمجرد أن يختار المستخدم اقتراحًا.