الانتقال إلى المحتوى

Places

عرض الأماكن والبحث عنها ثم قراءة تفاصيلها.

عرض أماكن منطقة

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 من بيئة خادمك.

المعاملات

المعاملات /v1/places
المعاملالقواعدالوصف
bboxإلزاميالاستعلام
  • مربع إحاطة
  • west,south,east,north بنظام WGS84، و2° على الأكثر لكل ضلع
المنطقة المطلوب عرضها.
categoriesاختياريالاستعلام
  • قائمة
  • القيم: healthcare، shopping، food، education، administration، transport، worship، accommodation
  • مفصولة بفواصل، كل قيمة مرة واحدة
  • 200 حرف على الأكثر
الاقتصار على هذه الفئات.
langاختياريالاستعلام
  • لغة
  • القيم: fr، ar
  • القيمة الافتراضية: fr
اللغة المفضلة للاسم المعروض.
limitاختياريالاستعلام
  • عدد صحيح
  • من 1 إلى 500
  • القيمة الافتراضية: 200
الحد الأقصى لعدد الأماكن المعادة.

الاستجابة

في المجموعة، تصف الحقول id وgeometry وproperties كل عنصر من features.

الاستجابة /v1/places
الحقلالوصف
featuresالنتائج، بالترتيب الذي تعيده الواجهة.
idمرجع المصدر osm:{type}/{id}. ليس معرّفًا دائمًا.
geometry.coordinatesالموقع [longitude, latitude] بنظام WGS84.
properties.displayالاسم المعروض (text وlanguage وsource_tag وfallback)، أو null لمكان بلا اسم.
properties.category.codelocality.<type> للتجمع السكاني، وإلا فهي فئة المكان.
properties.position.kindمصدر الموقع: نقطة OSM، أو نقطة محسوبة لمساحة.
meta.statusok عند وجود نتائج، وإلا no_match؛ وempty_catalog لفهرس تجمعات سكانية فارغ.
meta.matchedعدد الأماكن المطابقة قبل تطبيق الحد.
meta.truncatedtrue عندما يتجاوز 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 لنتيجة قائمة أو بحث.

المعاملات

المعاملات /v1/places/osm/{type}/{id}
المعاملالقواعدالوصف
typeإلزاميالمسار
  • نص
  • القيم: node، way
نوع عنصر OSM.
idإلزاميالمسار
  • عدد صحيح
  • عدد صحيح موجب من 20 رقمًا على الأكثر
معرّف عنصر OSM.
langاختياريالاستعلام
  • لغة
  • القيم: fr، ar
  • القيمة الافتراضية: fr
اللغة المفضلة للاسم المعروض.

الاستجابة

الاستجابة /v1/places/osm/{type}/{id}
الحقلالوصف
idمرجع المصدر osm:{type}/{id}. ليس معرّفًا دائمًا.
geometry.coordinatesالموقع [longitude, latitude] بنظام WGS84.
properties.displayالاسم المعروض (text وlanguage وsource_tag وfallback)، أو null لمكان بلا اسم.
properties.namesالأسماء التي يوفرها المصدر حسب وسم اللغة، دون أي ترجمة.
properties.category.codelocality.<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. اعرض هذه الإشارة مع رابطها حيثما تعرض البيانات:

© OpenStreetMap contributors