Places
عرض الأماكن والبحث عنها ثم قراءة تفاصيلها.
البحث عن الأماكن
GET/v1/places/search
يبحث في جميع أسماء المكان. لا يرتّب near إلا النتائج المتساوية في جودة المطابقة.
- الصلاحية المطلوبة
places:read- الاستجابة
application/geo+json
أمثلة
cURL
curl --get "$ATLAS_API_URL/v1/places/search" \
--header "Authorization: Bearer $ATLAS_API_KEY" \
--data-urlencode 'q=صيدلية' \
--data-urlencode 'lang=ar' \
--data-urlencode 'near=-15.9785,18.0858' \
--data-urlencode 'limit=5'Node.js
const url = new URL("/v1/places/search", process.env.ATLAS_API_URL);
url.search = new URLSearchParams({
q: "صيدلية",
lang: "ar",
near: "-15.9785,18.0858",
limit: "5",
}).toString();
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.ATLAS_API_KEY}` },
});
const body = await response.json();
if (!response.ok) throw new Error(`ATLASMR ${response.status} ${body.code}`);
console.log(body.meta.status, body.features.length);PHP
<?php
$url = getenv('ATLAS_API_URL') . '/v1/places/search?' . http_build_query([
'q' => 'صيدلية',
'lang' => 'ar',
'near' => '-15.9785,18.0858',
'limit' => '5',
], '', '&', PHP_QUERY_RFC3986);
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ATLAS_API_KEY')],
]);
$body = json_decode(curl_exec($curl), true, 512, JSON_THROW_ON_ERROR);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($status !== 200) {
throw new RuntimeException("ATLASMR {$status} {$body['code']}");
}
echo $body['meta']['status'], ' ', count($body['features']), PHP_EOL;تقرأ الأمثلة ATLAS_API_URL وATLAS_API_KEY من بيئة خادمك.
المعاملات
| المعامل | القواعد | الوصف |
|---|---|---|
q |
| الاسم المطلوب أو جزء منه. |
lang |
| اللغة المفضلة للاسم المعروض. |
categories |
| الاقتصار على هذه الفئات. |
near |
| نقطة ترتّب النتائج المتساوية في الجودة. |
limit |
| الحد الأقصى لعدد النتائج. |
الاستجابة
في المجموعة، تصف الحقول id وgeometry وproperties كل عنصر من features.
| الحقل | الوصف |
|---|---|
features | النتائج، بالترتيب الذي تعيده الواجهة. |
id | مرجع المصدر osm:{type}/{id}. ليس معرّفًا دائمًا. |
geometry.coordinates | الموقع [longitude, latitude] بنظام WGS84. |
properties.display | الاسم المعروض (text وlanguage وsource_tag وfallback)، أو null لمكان بلا اسم. |
properties.category.code | locality.<type> للتجمع السكاني، وإلا فهي فئة المكان. |
properties.reference | مرجع OSM (source وtype وid وkey). قد يتغير من فهرس إلى آخر. |
properties.match | كيف وجد الطلب هذه النتيجة: type المطابقة والاسم المطابق. |
meta.status | ok عند وجود نتائج، وإلا no_match؛ وempty_catalog لفهرس تجمعات سكانية فارغ. |
meta.matched | عدد الأماكن المطابقة قبل تطبيق الحد. |
meta.catalog.notices | تنبيهات حول الفهرس، ينبغي أن تعكسها واجهتك. |
meta.attribution | الإشارة التي يجب عرضها حيثما تعرض هذه البيانات. |
الأخطاء
تتبع جميع الأخطاء صيغة Problem Details.
عرض أماكن منطقة
GET/v1/places
يعيد الأماكن الأقرب إلى مركز مربع الإحاطة.
- الصلاحية المطلوبة
places:read- الاستجابة
application/geo+json
أمثلة
cURL
curl --get "$ATLAS_API_URL/v1/places" \
--header "Authorization: Bearer $ATLAS_API_KEY" \
--data-urlencode 'bbox=-15.99,18.07,-15.95,18.11' \
--data-urlencode 'categories=healthcare' \
--data-urlencode 'lang=ar' \
--data-urlencode 'limit=100'Node.js
const url = new URL("/v1/places", process.env.ATLAS_API_URL);
url.search = new URLSearchParams({
bbox: "-15.99,18.07,-15.95,18.11",
categories: "healthcare",
lang: "ar",
limit: "100",
}).toString();
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.ATLAS_API_KEY}` },
});
const body = await response.json();
if (!response.ok) throw new Error(`ATLASMR ${response.status} ${body.code}`);
console.log(body.meta.status, body.features.length);PHP
<?php
$url = getenv('ATLAS_API_URL') . '/v1/places?' . http_build_query([
'bbox' => '-15.99,18.07,-15.95,18.11',
'categories' => 'healthcare',
'lang' => 'ar',
'limit' => '100',
], '', '&', PHP_QUERY_RFC3986);
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ATLAS_API_KEY')],
]);
$body = json_decode(curl_exec($curl), true, 512, JSON_THROW_ON_ERROR);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($status !== 200) {
throw new RuntimeException("ATLASMR {$status} {$body['code']}");
}
echo $body['meta']['status'], ' ', count($body['features']), PHP_EOL;تقرأ الأمثلة ATLAS_API_URL وATLAS_API_KEY من بيئة خادمك.
المعاملات
| المعامل | القواعد | الوصف |
|---|---|---|
bbox |
| المنطقة المطلوب عرضها. |
categories |
| الاقتصار على هذه الفئات. |
lang |
| اللغة المفضلة للاسم المعروض. |
limit |
| الحد الأقصى لعدد الأماكن المعادة. |
الاستجابة
في المجموعة، تصف الحقول id وgeometry وproperties كل عنصر من features.
| الحقل | الوصف |
|---|---|
features | النتائج، بالترتيب الذي تعيده الواجهة. |
id | مرجع المصدر osm:{type}/{id}. ليس معرّفًا دائمًا. |
geometry.coordinates | الموقع [longitude, latitude] بنظام WGS84. |
properties.display | الاسم المعروض (text وlanguage وsource_tag وfallback)، أو null لمكان بلا اسم. |
properties.category.code | locality.<type> للتجمع السكاني، وإلا فهي فئة المكان. |
properties.position.kind | مصدر الموقع: نقطة OSM، أو نقطة محسوبة لمساحة. |
meta.status | ok عند وجود نتائج، وإلا no_match؛ وempty_catalog لفهرس تجمعات سكانية فارغ. |
meta.matched | عدد الأماكن المطابقة قبل تطبيق الحد. |
meta.truncated | true عندما يتجاوز matched قيمة limit: صغّر المنطقة أو استخدم عامل تصفية. |
meta.catalog.notices | تنبيهات حول الفهرس، ينبغي أن تعكسها واجهتك. |
meta.attribution | الإشارة التي يجب عرضها حيثما تعرض هذه البيانات. |
الأخطاء
تتبع جميع الأخطاء صيغة Problem Details.
قراءة مكان
GET/v1/places/osm/{type}/{id}
يعيد مكانًا بمرجعه في OSM، مع تفاصيل المصدر المسموح بها.
- الصلاحية المطلوبة
places:read- الاستجابة
application/geo+json
أمثلة
كوّن المسار من properties.reference.type وproperties.reference.id لنتيجة قائمة أو بحث.
المعاملات
| المعامل | القواعد | الوصف |
|---|---|---|
type |
| نوع عنصر OSM. |
id |
| معرّف عنصر OSM. |
lang |
| اللغة المفضلة للاسم المعروض. |
الاستجابة
| الحقل | الوصف |
|---|---|
id | مرجع المصدر osm:{type}/{id}. ليس معرّفًا دائمًا. |
geometry.coordinates | الموقع [longitude, latitude] بنظام WGS84. |
properties.display | الاسم المعروض (text وlanguage وsource_tag وfallback)، أو null لمكان بلا اسم. |
properties.names | الأسماء التي يوفرها المصدر حسب وسم اللغة، دون أي ترجمة. |
properties.category.code | locality.<type> للتجمع السكاني، وإلا فهي فئة المكان. |
properties.info | تفاصيل المصدر المسموح بها، مثل ساعات العمل أو الهاتف، كما يكتبها المصدر. |
meta.catalog.notices | تنبيهات حول الفهرس، ينبغي أن تعكسها واجهتك. |
meta.attribution | الإشارة التي يجب عرضها حيثما تعرض هذه البيانات. |
الأخطاء
تتبع جميع الأخطاء صيغة Problem Details.
التنبيهات والإشارة إلى المصدر
تذكر كل استجابة تنبيهاتها في meta.catalog.notices:
experimental_catalog- فهرس تجريبي: قد يتغير محتواه وشكله.
partial_coverage- تغطية جزئية: قد يوجد مكان غير مدرج.
unverified_source- بيانات مصدر لم تتحقق منها ATLASMR.
not_linked_to_map_release- غير مرتبط بإصدار الخريطة: قد تختلف المواقع والأسماء عن الخريطة الأساسية.
مصدر البيانات OpenStreetMap، بترخيص ODbL 1.0. اعرض هذه الإشارة مع رابطها حيثما تعرض البيانات: