Using Geolocاستخدام Geoloc

What it doesما يفعله

You give it an IP address. It tells you which country that address is in, and how sure it is. That is the whole product, and the terseness is the point.تُعطيه عنوان IP. فيُخبرك في أي دولة يقع ذلك العنوان، وما مدى يقينه. هذا هو المنتج كله، والإيجاز مقصود.

The common case — where is this request coming from? — is two bytes and a single round trip, with nothing to install, nothing to sign up for, and nothing to parse.الحالة الشائعة — من أين يأتي هذا الطلب؟ — بايتان ورحلة ذهاب وإياب واحدة، بلا شيء تُثبّته، ولا تسجيل، ولا تحليل.

And the rule to know before anything else: an address we cannot place comes back as ??, never a guess. "We don't know" is a real answer, and it is worth more than a plausible wrong one — ?? is unmistakable at a glance, which is the whole point of it.والقاعدة التي ينبغي معرفتها قبل كل شيء: العنوان الذي لا نستطيع تحديده يعود بـ??، لا بتخمينٍ أبداً. «لا نعرف» إجابة حقيقية، وهي أثمن من إجابة معقولة خاطئة — و?? لا يُخطئه النظر، وذلك تحديداً المقصود منه.

$ curl https://geoloc.ali-web-services.com/
SA   # ISO code for Saudi Arabia — the country of the caller's IP

How it behaves, in one screenكيف يتصرّف، في شاشة واحدة

There is no database server, no cache tier, and no moving parts to be down. The database it answers from is part of the service itself, not something it calls. The consequences are what make it fast, and they are worth spelling out.لا خادم قاعدة بيانات، ولا طبقة تخزين مؤقت، ولا أجزاء متحرّكة تتعطّل. وقاعدة البيانات التي يُجيب منها جزءٌ من الخدمة نفسها، لا شيء يناديه. والنتائج هي ما يجعله سريعاً، وتستحقّ التوضيح.

How a request is servedكيف يُخدَم الطلب

1. caller → geolocالمتصل ← geoloc
   A plain HTTP request arrives — no key, no body, no ceremony.يصل طلب HTTP عادي — بلا مفتاح، ولا جسم، ولا مراسم.
2. in memoryفي الذاكرة
   An in-memory lookup against the embedded database resolves the address. Nanoseconds; no network call leaves the process.بحث في الذاكرة مقابل قاعدة البيانات المُضمَّنة يحلّ العنوان. نانوثوانٍ؛ ولا نداء شبكة يغادر العملية.
3. geoloc → callergeoloc ← المتصل
   A bare country code comes back, with confidence and detail in X-Geoloc-* headers. Nothing is written down.يعود رمز دولة مجرّد، مع الثقة والتفاصيل في ترويسات X-Geoloc-*. ولا يُدوَّن شيء.

The endpointsالنقاط

Try itجرِّبه

$ curl https://geoloc.ali-web-services.com/

SA   # ISO code for Saudi Arabia — the country of the caller's IP

The country codeرمز الدولة

The root endpoint answers for whoever is calling. The body is a bare ISO 3166-1 alpha-2 code, so it drops straight into a shell script without a JSON parser in the way.النقطة الجذرية تُجيب عمّن يتّصل. والجسم رمز مجرّد بمعيار ISO 3166-1 alpha-2، فيدخل مباشرةً في سكربت طرفية دون محلّل JSON يعترض.

$ curl https://geoloc.ali-web-services.com/
SA   # ISO code for Saudi Arabia — the country of the caller's IP

Everything else we know and are willing to stand behind rides along in the response headers, so a client that wants more never needs a second request.وكل ما نعرفه ونستعدّ لتحمّل مسؤوليته يركب في ترويسات الاستجابة، فالعميل الذي يريد المزيد لا يحتاج طلباً ثانياً أبداً.

$ curl -i https://geoloc.ali-web-services.com/

X-Geoloc-Country:    SA
X-Geoloc-Found:      true
X-Geoloc-Confidence: 0.90
X-Geoloc-Updated:    2026-08-02

A specific addressعنوان بعينه

$ curl https://geoloc.ali-web-services.com/v1/ip/8.8.8.8
US

When we don't knowحين لا نعرف

An address we cannot place comes back as ?? — a 200 with the country ?? and the header X-Geoloc-Found: false. That is a real answer, not an error: "we cannot place this" is a different thing from a missing endpoint and from a network failure, and folding all three onto a 404 only makes a caller pull them apart again. A sentinel is one response shape to parse and one header to branch on.العنوان الذي لا نستطيع تحديده يعود بـ?? — أي 200 برمز الدولة ?? والترويسة X-Geoloc-Found: false. وهذا إجابة حقيقية لا خطأ: «لا نستطيع تحديده» شيء يخالف نقطةً مفقودة، ويخالف عطلاً في الشبكة، ودمج الثلاثة في 404 واحد لا يفعل إلا أن يُرغم المتصل على تفكيكها ثانيةً. أما الرمز الدلالي فهو شكل استجابة واحد يُحلَّل، وترويسة واحدة يُتفرَّع عليها.

$ curl -i https://geoloc.ali-web-services.com/v1/ip/10.0.0.1
HTTP/2 200
X-Geoloc-Country:    ??
X-Geoloc-Found:      false
X-Geoloc-Confidence: 0.00

??

JSON, when you want structureJSON، حين تريد بنية

$ curl https://geoloc.ali-web-services.com/json
{
  "ip": "84.235.1.1",
  "country": "SA",
  "country_name": { "en": "Saudi Arabia", "ar": "المملكة العربية السعودية" },
  "confidence": 0.9,
  "updated": "2026-08-01",
  "found": true
}

Your own IPعنوانك أنت

$ curl https://geoloc.ali-web-services.com/ip
84.235.1.1

Many at onceدفعة واحدة

POST /v1/bulk takes up to 1000 addresses in one request — a plain list, one per line, or a JSON array. It answers with JSON; send Accept: text/plain and you get one country code per line instead. Order and duplicates are preserved, so the response lines up with your input file position for position; you never have to match an answer back to an address.‏POST /v1/bulk يقبل حتى 1000 عنوان في طلب واحد — قائمة صِرفة، عنوان في كل سطر، أو مصفوفة JSON. ويُجيب بـ JSON؛ وإن أرسلت Accept: text/plain حصلت على رمز دولة في كل سطر بدلاً من ذلك. يُحفَظ الترتيب والتكرار، فتصطفّ الاستجابة مع ملف مُدخَلك سطراً بسطر؛ ولا تُطابق إجابةً بعنوان أبداً.

$ curl -sX POST https://geoloc.ali-web-services.com/v1/bulk \
       -H "Accept: text/plain" --data-binary @addresses.txt
US
??
NL

A malformed entry never fails the batch — it comes back flagged, and stays distinguishable from an address that simply cannot be placed, which is ?? here as everywhere else.المُدخَل المشوَّه لا يُفشِل الدفعة أبداً — بل يعود موسوماً، ويبقى مميَّزاً عن عنوان لا يمكن تحديده فحسب، وهو ?? هنا كما في كل مكان.

Run lookups locallyشغّل عمليات البحث محلياً

A fresh database is generated every day and published on the website, in MMDB format — read natively by nginx, Envoy, Logstash, Vector and libraries in every mainstream language. Download the whole thing — no account, no key, about 4 MB, rebuilt daily. If you already run IP lookups locally, switching to ours is a path in a config file rather than an integration project.تُولَّد قاعدة بيانات جديدة كل يوم وتُنشر على الموقع، بصيغة MMDB — تقرؤها أصلاً nginx وEnvoy وLogstash وVector ومكتبات كل لغة رئيسية. نزِّلها كاملةً — بلا حساب، ولا مفتاح، نحو 4 ميغابايت، تُعاد بناءً يومياً. وإن كنت تُجري عمليات بحث IP محلياً أصلاً، فالتحوّل إلى قاعدتنا مسارٌ في ملف إعداد لا مشروع تكامل.

Download the database → latest.mmdbنزِّل قاعدة البيانات ← latest.mmdb

Downloads support conditional requests, so a nightly cron transfers nothing on the days the file has not meaningfully changed.تدعم التنزيلات الطلبات الشرطية، فمهمة cron ليلية لا تنقل شيئاً في الأيام التي لم يتغيّر فيها الملف تغيّراً ذا معنى.

curl -sf -z /var/lib/geoloc/geoloc.mmdb \
        -o /var/lib/geoloc/geoloc.mmdb \
        https://geoloc.ali-web-services.com/v1/db/latest.mmdb

A checksum and a signature are published alongside it, so you can verify what you are about to load into production.يُنشر معها مجموع تحقّق وتوقيع، فتستطيع التحقّق ممّا أنت على وشك تحميله في الإنتاج.

The database is dual-licensed — MIT or CC BY 4.0, your choice. Take MIT and get on with it unless your legal team has a reason to prefer the other.قاعدة البيانات مزدوجة الترخيص — MIT أو CC BY 4.0، والخيار لك. خذ MIT وامضِ في عملك ما لم يكن لدى فريقك القانوني سبب لتفضيل الآخر.

How the database reaches youكيف تصلك قاعدة البيانات

1. daily, in CIيومياً، في التكامل المستمر
   A fresh database is built and shipped by the same pipeline that deploys the service — the serving data and the downloadable file are never out of step.تُبنى قاعدة بيانات جديدة وتُشحن عبر خط الأنابيب نفسه الذي ينشر الخدمة — فبيانات الخدمة والملف القابل للتنزيل لا يفترقان أبداً.
2. publishedمنشور
   It is posted on the website with a checksum and a signature beside it.يُنشر على الموقع ومعه مجموع تحقّق وتوقيع.
3. your croncron لديك
   Your nightly job fetches it — only if it changed. A conditional request means most nights transfer nothing at all.مهمتك الليلية تجلبه — فقط إن تغيّر. والطلب الشرطي يعني أن معظم الليالي لا تنقل شيئاً البتّة.

A public stub for your testsخادم بديل عام لاختباراتك

There is a public stub server to build your end-to-end tests against — point your test stack at it instead of at us. It speaks the same contract as the real service and adds the two things a live service can never give a test suite: deterministic answers, and failure paths you can summon on demand.ثمّة خادم بديل عام لتبني عليه اختباراتك الطرفية — وجِّه مجموعتك الاختبارية إليه بدلاً منّا. يتحدّث العقد نفسه كالخدمة الحقيقية، ويضيف الشيئين اللذين لا تستطيع خدمة حيّة أن تمنحهما مجموعةً اختبارية: إجابات حتمية، ومسارات إخفاق تستدعيها عند الطلب.

docker run --rm -p 8080:8080 \
  europe-west1-docker.pkg.dev/ali-web-services/stub-servers/geoloc-stub:latest

The image is public and needs no credentials — linux/amd64 and linux/arm64.الصورة عامة ولا تحتاج بيانات اعتماد — linux/amd64 وlinux/arm64.

Test addresses come from the RFC 5737 documentation ranges, which are guaranteed never to be routed — so a test address can never collide with a real answer.عناوين الاختبار من نطاقات التوثيق في RFC 5737، المضمونِ ألّا تُوجَّه أبداً — فلا يتصادم عنوان اختبار مع إجابة حقيقية قط.

The running container lists its own matrix at /_stub/scenarios, takes extra cases through STUB_SCENARIOS, and answers "was this endpoint called, and how often?" — so you assert on calls without reading logs.الحاوية العاملة تسرد مصفوفتها في /_stub/scenarios، وتقبل حالات إضافية عبر STUB_SCENARIOS، وتُجيب عن «هل نُودِيت هذه النقطة، وكم مرة؟» — فتتحقّق من النداءات دون قراءة السجلّات.

curl -s localhost:8080/_stub/verify \
  -d '{"path":"/v1/ip/{ip}","ip":"192.0.2.1","times":"once"}'
{ "ok": true, "matched": 1, "expected": "exactly once" }

Accuracy, and saying "I don't know"الدقّة، وقول «لا أعرف»

Every answer carries a confidence score. It is a real measurement of how well the evidence agrees, not a decorative number, and it is there because the alternative is worse.كل إجابة تحمل درجة ثقة. وهي قياس حقيقي لمدى اتّفاق الأدلة، لا رقم زخرفي، وهي هناك لأن البديل أسوأ.

This matters more than it sounds. The standard failure of IP geolocation is not admitting ignorance — it is answering confidently and wrongly. Whole ranges get assigned to a country's largest city because a point had to be returned, and downstream that fabricated point is indistinguishable from a real one. Systems make decisions on it. Nobody finds out.هذا أهمّ ممّا يبدو. الإخفاق المعتاد في تحديد الموقع عبر IP ليس الاعتراف بالجهل — بل الإجابة بثقة وخطأ. تُسنَد نطاقات كاملة إلى أكبر مدن الدولة لأنه كان لا بدّ من إرجاع نقطة، وفي المصبّ لا تتمّيز تلك النقطة المُلفَّقة عن نقطة حقيقية. تبني الأنظمة قرارات عليها. ولا يكتشف أحد.

We would rather return less and have all of it be true. If a field is present, we are prepared to defend it; if it is missing, that is information too.نُفضّل أن نُرجع أقلّ وأن يكون كله صحيحاً. إن حضر حقل، فنحن مستعدّون للدفاع عنه؛ وإن غاب، فذلك معلومة أيضاً.

Looking up an address does not create a record of itالبحث عن عنوان لا يُنشئ سجلّاً به

• Request logging is disabled. Not filtered afterwards — not collected.تسجيل الطلبات مُعطَّل. لا يُرشَّح لاحقاً — بل لا يُجمَع.
• Addresses are processed transiently, in memory, for the duration of the request, and are never written to disk.تُعالَج العناوين عابرةً، في الذاكرة، طوال مدة الطلب، ولا تُكتَب على القرص أبداً.
• Abuse-prevention counters that keep the free endpoint usable work on a salted hash that rotates hourly, held in memory with a lifetime measured in seconds.عدّادات منع إساءة الاستخدام التي تُبقي النقطة المجانية صالحة تعمل على تجزئة مُملَّحة تتبدّل كل ساعة، محفوظة في الذاكرة بعمر يُقاس بالثواني.
• No cookies, no tracking, and nothing to opt out of.لا كوكيز، ولا تتبّع، ولا شيء تنسحب منه.

The service holds aggregate information about network ranges. It does not hold information about you, and its design makes that a property of the architecture rather than a promise about our intentions.تحمل الخدمة معلومات مجمّعة عن نطاقات الشبكة. ولا تحمل معلومات عنك، وتصميمها يجعل ذلك خاصّيةً في البنية لا وعداً عن نوايانا.

Open, with limits that keep it openمفتوح، بحدود تُبقيه مفتوحاً

The public endpoint is open and requires no key. Here are the numbers. Responses carry standard RateLimit-* headers so you always know where you stand, and CORS is fully open so it works from the browser.النقطة العامة مفتوحة ولا تتطلّب مفتاحاً. وهذه هي الأرقام. تحمل الاستجابات ترويسات RateLimit-* قياسية فتعرف دائماً أين أنت، وCORS مفتوح تماماً فيعمل من المتصفّح.

Bulk carries up to 1000 addresses a call, so ten calls a minute is 10,000 addresses a minute — far more throughput than single lookups. Batching is genuinely cheaper for both sides, which is why it is budgeted that way.تحمل الدفعة حتى 1000 عنوان في الطلب، فعشرة طلبات في الدقيقة تعني 10,000 عنوان في الدقيقة — إنتاجية أعلى بكثير من الاستعلامات المفردة. والتجميع أرخص فعلاً للطرفين، ولذلك رُصد على هذا النحو.

Calling from the browser barely counts against you. A request made from a page is attributed to the visitor's address, not to your server — so a busy website spends almost none of this budget. Developers usually assume the opposite.النداء من المتصفّح لا يكاد يُحتسب عليك. يُنسب الطلب الصادر من صفحة إلى عنوان الزائر لا إلى خادمك — فالموقع المزدحم لا ينفق من هذا الرصيد إلا القليل. وعادةً ما يفترض المطوّرون العكس.

Still no key and no account, and that is not going to change. If your volume runs into these numbers, download the database and look addresses up locally — no limit, no key, no network call.لا يزال بلا مفتاح ولا حساب، ولن يتغيّر ذلك. وإن بلغ حجمك هذه الأرقام، فنزّل قاعدة البيانات واستعلم محلياً — بلا حد، ولا مفتاح، ولا نداء عبر الشبكة.

What it does not do — yet, or at allما لا يفعله — بعدُ، أو البتّة

Stated plainly, because knowing the edges up front is worth more than discovering them later.مذكور بوضوح، لأن معرفة الحدود مقدَّماً أثمن من اكتشافها لاحقاً.

• Country only, for now. Region and city are being worked on and are not published. They will be, each with its own confidence score, once they clear the bar the country data already clears. Accuracy inside Saudi Arabia is the specific thing under active improvement.الدولة فقط في الوقت الحالي. المنطقة والمدينة قيد العمل ولم تُنشرا. وستُنشران، كلٌّ بدرجة ثقته، متى تجاوزتا العتبة التي تجاوزتها بيانات الدولة أصلاً. والدقّة داخل المملكة العربية السعودية هي تحديداً ما يجري تحسينه بنشاط.
• Not a fraud or VPN-detection product. Proxy, VPN and residential-proxy classification is a different problem with different evidence, and we would rather not offer it than offer a version that is wrong often enough to be a liability.ليس منتجاً لكشف الاحتيال أو VPN. تصنيف الوكيل وVPN والوكيل المنزلي مسألة مختلفة بأدلة مختلفة، ونُفضّل ألّا نوفّره على أن نوفّر نسخةً خاطئة بما يكفي لتكون عبئاً.
• It does not identify people, households or businesses. It answers questions about network address ranges. There is no individual-level data in it, and there is not intended to be.لا يُعرّف أشخاصاً ولا أُسراً ولا شركات. يُجيب عن أسئلة تخصّ نطاقات عناوين الشبكة. لا بيانات على مستوى الأفراد فيه، ولا يُقصَد أن تكون.
• Not a mapping or routing platform. It does one thing.ليس منصّة خرائط أو توجيه. يفعل شيئاً واحداً.

Built in Saudi Arabiaصُنع في المملكة العربية السعودية

Geoloc is built in Saudi Arabia, for Saudi Arabia — and it is offered to anyone else who wants it. That is a statement about where the attention goes.‏Geoloc مصنوع في المملكة العربية السعودية، من أجلها — ومعروض لكل من أراده سواها. وهذا قولٌ عن حيث تتّجه العناية.

Global providers treat the Kingdom as a rounding error: ranges collapsed onto a single city, mobile networks misread, Arabic place names mangled. Being here means those are our own users' problems rather than an edge case in someone else's backlog, and they get fixed accordingly.يعامل المزوّدون العالميون المملكة كخطأ تقريب: نطاقات تنهار على مدينة واحدة، وشبكات جوّال تُقرأ خطأً، وأسماء أماكن عربية مشوّهة. ووجودنا هنا يعني أن تلك مشكلاتُ مستخدمينا نحن لا حالةٌ هامشية في قائمة عمل غيرنا، فتُصلَح تبعاً لذلك.