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

العثور على مكان (الإصدار القديم)

المطوّرون في المنطقة الاقتصادية الأوروبية

ملاحظة: مكتبات جهة الخادم ومن جهة العميل

تتوفّر Places API أيضًا مع عميل Java وعميل Python وعميل Go وعميل Node.js لخدمات "خرائط Google". تُستخدم واجهة برمجة التطبيقات Places API ومكتبات البرامج في تطبيقات الخادم.

إذا كنت بصدد إنشاء تطبيق من جهة العميل، يمكنك الاطّلاع على حزمة تطوير البرامج بالاستناد إلى المكان لنظام التشغيل Android (الجديدة) وحزمة تطوير البرامج بالاستناد إلى المكان لنظام التشغيل iOS (الجديدة) ومكتبة الأماكن في Maps JavaScript API.

يأخذ طلب "البحث عن مكان" (الإصدار القديم) نصًا كإدخال ويعرض مكانًا. يمكن أن يكون الإدخال أي نوع من البيانات النصية للأماكن، مثل الاسم أو العنوان أو رقم الهاتف. يجب أن يكون الطلب سلسلة. يؤدي طلب "العثور على مكان (الإصدار القديم)" باستخدام بيانات غير نصية، مثل إحداثيات خطوط العرض/الطول أو رمز Plus Code، إلى حدوث خطأ.

يعرض طلب "العثور على مكان" (القديم) مجموعة فرعية من الحقول التي يعرضها طلب تفاصيل المكان (القديم). لمزيد من المعلومات عن الحقول غير المتاحة في طلب Find Place (الإصدار القديم)، يُرجى الاطّلاع على الحقول المتوافقة في Places API. إذا لم يتم عرض الحقل الذي تريده، يمكنك استخدام واجهة برمجة التطبيقات العثور على مكان (قديم) للحصول على place_id، ثم استخدام رقم التعريف هذا لإرسال طلب إلى واجهة برمجة التطبيقات تفاصيل المكان (قديم).

طلبات Find Place (Legacy)

طلب "العثور على مكان" (قديم) هو عنوان URL يستخدم HTTP بالشكل التالي:

https://maps.googleapis.com/maps/api/place/findplacefromtext/output?parameters

حيث يمكن أن تكون output أيًا من القيم التالية:

json (يُنصح به) يشير إلى الإخراج بتنسيق JavaScript Object Notation ‏ (JSON)
‫xml يشير إلى أنّ الناتج بتنسيق XML

يجب توفير مَعلمات معيّنة لبدء طلب "العثور على مكان" (الإصدار القديم). وكما هو معتاد في عناوين URL، يتم الفصل بين جميع المَعلمات باستخدام علامة العطف (&).

المعلمات المطلوبة

إدخال

سلسلة النص المطلوب البحث عنها يجب أن تكون هذه السمة اسم مكان أو عنوانًا أو رقم هاتف (على سبيل المثال، "123 الشارع الرئيسي" أو "مبنى البلدية").

ملاحظة مهمة: يجب أن تكون قيمة السمة input سلسلة. يؤدي طلب "العثور على مكان (قديم)" باستخدام بيانات غير نصية، مثل إحداثيات خطوط العرض وخطوط الطول أو رمز Plus Code، إلى حدوث خطأ.

inputtype

نوع الإدخال يمكن أن يكون هذا إما textquery أو phonenumber. يجب أن تكون أرقام الهواتف بالتنسيق الدولي (مسبوقة بعلامة زائد (+)، متبوعة برمز البلد، ثم رقم الهاتف نفسه). يمكنك الاطّلاع على توصية E.164 الصادرة عن الاتحاد الدولي للاتصالات لمزيد من المعلومات.

المعلمات الاختيارية

fields

تنبيه: لا تعرض طلبات "البحث عن الأماكن (الإصدار القديم)" وطلبات "تفاصيل المكان (الإصدار القديم)" الحقول نفسها. تعرض طلبات "البحث عن الأماكن (الإصدار القديم)" مجموعة فرعية من الحقول التي تعرضها طلبات "تفاصيل المكان (الإصدار القديم)". إذا لم يعرض "البحث عن الأماكن (الإصدار القديم)" الحقل الذي تريده، يمكنك استخدام "البحث عن الأماكن (الإصدار القديم)" للحصول على place_id، ثم استخدام رقم تعريف المكان هذا لتقديم طلب "تفاصيل المكان (الإصدار القديم)". لمزيد من المعلومات عن الحقول غير المتاحة في طلب "البحث عن الأماكن (الإصدار القديم)"، يُرجى الاطّلاع على الحقول المتوافقة في Places API.

استخدِم مَعلمة الحقول لتحديد قائمة قيم مفصولة بفاصلة لأنواع بيانات الأماكن المطلوب عرضها. على سبيل المثال: fields=formatted_address,name,geometry. استخدِم شرطة مائلة للأمام عند تحديد قيم مركّبة. على سبيل المثال: opening_hours/open_now.

تنقسم الحقول إلى ثلاث فئات للفوترة: أساسية ومعلومات الاتصال والأجواء. تتم فوترة الحقول الأساسية بالسعر الأساسي، وتتم فوترة حقول "جهة الاتصال" و"الأجواء" بسعر أعلى. يتم تحصيل رسوم وحدات SKU الأساسية ووحدات SKU الخاصة بجهات الاتصال ووحدات SKU الخاصة بالأجواء بالإضافة إلى وحدة SKU الأساسية (تفاصيل المكان أو العثور على مكان أو البحث في الجوار أو البحث النصي) للطلب الذي أدّى إلى تفعيلها. لمزيد من المعلومات، يُرجى الاطّلاع على ورقة بيانات الأسعار.

الأساسية

تتضمّن الفئة "أساسية" الحقول التالية: address_components وadr_address وbusiness_status وformatted_address وgeometry وicon وicon_mask_base_uri وicon_background_color وname وpermanently_closed (متوقّفة نهائيًا) وphoto وplace_id وplus_code وtype وurl وutc_offset وvicinity وwheelchair_accessible_entrance.

التواصل

تتضمّن فئة "جهة الاتصال" الحقول التالية: current_opening_hours وformatted_phone_number وinternational_phone_number وopening_hours وsecondary_opening_hours وwebsite

الأجواء

تتضمّن فئة "الأجواء" الحقول التالية: curbside_pickup وdelivery وdine_in وeditorial_summary وprice_level وrating وreservable وreviews وserves_beer وserves_breakfast وserves_brunch وserves_dinner وserves_lunch وserves_vegetarian_food وserves_wine وtakeout وuser_ratings_total.

ملاحظة: يتم دائمًا عرض معلومات تحديد المصدر، html_attributions، مع كل طلب، بغض النظر عمّا إذا تم طلب الحقل أم لا.

language

اللغة التي سيتم عرض النتائج بها

اطّلِع على قائمة اللغات المتاحة. تعدّل Google اللغات المتاحة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
في حال عدم توفير language، تحاول واجهة برمجة التطبيقات استخدام اللغة المفضّلة كما هو محدّد في العنوان Accept-Language.
تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض عناوين الشوارع باللغة المحلية، ويتم تحويلها صوتيًا إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
إذا لم يكن الاسم متاحًا باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.
تؤثر اللغة المفضّلة بشكل بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وفي ترتيب عرضها. تفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة واحدة ولكن ليس في لغة أخرى. على سبيل المثال، utca وtér هما مرادفان لكلمة "شارع" باللغة الهنغارية.

locationbias

تفضيل النتائج في منطقة محدّدة، من خلال تحديد نطاق جغرافي بالإضافة إلى خطوط العرض/الطول، أو زوجَين من خطوط العرض/الطول يمثّلان نقاط مستطيل في حال عدم تحديد هذه المَعلمة، تستخدم واجهة برمجة التطبيقات انحياز عنوان IP تلقائيًا.

انحياز عنوان IP: يوجّه واجهة برمجة التطبيقات لاستخدام انحياز عنوان IP. مرِّر السلسلة ipbias (لا يتضمّن هذا الخيار مَعلمات إضافية).
دائري: سلسلة تحدّد نصف القطر بالأمتار، بالإضافة إلى خط العرض/خط الطول بالدرجات العشرية. استخدِم التنسيق التالي: circle:radius@lat,lng.
مستطيل: سلسلة تحدّد زوجَين من خطوط العرض/الطول بالدرجات العشرية، وتمثّل النقاط الجنوبية/الغربية والشمالية/الشرقية لمستطيل. استخدِم التنسيق التالي:rectangle:south,west|north,east. يُرجى العِلم أنّ قيم الشرق/الغرب يتم تقريبها إلى النطاق -180 و180، وقيم الشمال/الجنوب يتم تقريبها إلى النطاق -90 و90.

ملاحظة: في حال حذف المَعلمة fields من طلب Find Place (Legacy)، سيتم عرض place_id فقط للنتيجة.

أمثلة على Find Place (الإصدار القديم)

يعرض المثال التالي طلب Find Place (Legacy) عن "متحف الفن المعاصر في أستراليا"، بما في ذلك الحقول photos وformatted_address وname وrating وopening_hours وgeometry:

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

يعرض المثال التالي طلب "البحث عن مكان (ميزة قديمة)" عن "مطعم مشاوي منغولي"، باستخدام المَعلمة locationbias لتفضيل النتائج ضمن 2000 متر من الإحداثيات المحدّدة:

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

يوضّح المثال التالي طلب "العثور على مكان" (قديم) لرقم هاتف. يُرجى العِلم أنّه تم ترميز بادئة الاتصال الدولية "+" إلى %2B لكي يكون هذا الطلب عنوان URL متوافقًا. إذا لم يتم ترميز البادئة +، سيتم فك ترميزها إلى مسافة على الخادم، ما يؤدي إلى عملية بحث غير صالحة عن رقم الهاتف.

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

استجابات Find Place (Legacy)

تحتوي استجابة "العثور على مكان" (الإصدار القديم) على أنواع البيانات التي تم تحديدها فقط باستخدام مَعلمة fields، بالإضافة إلى html_attributions. يعرض المثال التالي الاستجابة لطلب "العثور على مكان (الإصدار القديم)" عن "متحف الفن المعاصر في أستراليا"، بما في ذلك الحقول formatted_address وgeometry وname وopening_hours وphotos وrating.

JSON

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

PlacesFindPlaceFromTextResponse

الحقل	مطلوب	النوع	الوصف
`candidates`	مطلوب	Array<Place>	يحتوي على مصفوفة من الأماكن المرشّحة. تعرض طلبات "البحث عن الأماكن (الإصدار القديم)" مجموعة فرعية من الحقول التي تعرضها طلبات "تفاصيل المكان (الإصدار القديم)". إذا لم يعرض "البحث عن الأماكن (الإصدار القديم)" الحقل الذي تريده، يمكنك استخدام "البحث عن الأماكن (الإصدار القديم)" للحصول على place_id، ثم استخدام رقم تعريف المكان هذا لتقديم طلب "تفاصيل المكان (الإصدار القديم)". لمزيد من المعلومات، يُرجى الاطّلاع على المكان.
`status`	مطلوب	PlacesSearchStatus	يحتوي على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبُّع سبب تعذُّر الطلب. يُرجى الاطّلاع على PlacesSearchStatus لمزيد من المعلومات.
`error_message`	اختياري	سلسلة	عندما تعرض الخدمة رمز حالة غير `OK<`، قد يكون هناك حقل `error_message` إضافي ضمن عنصر الاستجابة. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن الأسباب وراء رمز الحالة المحدّد. لا يتم عرض هذا الحقل دائمًا، ومحتواه عرضة للتغيير.
`info_messages`	اختياري	Array<string>	عندما تعرض الخدمة معلومات إضافية حول مواصفات الطلب، قد يكون هناك حقل `info_messages` إضافي ضمن عنصر الاستجابة. لا يتم عرض هذا الحقل إلا للطلبات الناجحة. وقد لا يتم عرضه دائمًا، كما أنّ محتواه عرضة للتغيير.

PlacesSearchStatus

رموز الحالة التي تعرضها الخدمة

‫OK يشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات تم بنجاح.
ZERO_RESULTS يشير إلى أنّ عملية البحث كانت ناجحة ولكن لم يتم عرض أي نتائج. قد يحدث ذلك إذا تم تمرير latlng في موقع جغرافي بعيد إلى عملية البحث.
‫INVALID_REQUEST تشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات مكتوب بشكلٍ غير صحيح، ويعود ذلك بشكل عام إلى عدم توفّر مَعلمة طلب البحث المطلوبة (location أو radius).
OVER_QUERY_LIMIT يشير إلى أيّ مما يلي:
- لقد تجاوزت الحد الأقصى لعدد الطلبات في الثانية.
- لم يتم تفعيل الفوترة في حسابك.
- تم تجاوز الرصيد الشهري البالغ 200 دولار أمريكي أو الحد الأقصى للاستخدام الذي فرضته بنفسك.
- لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).
يمكنك الاطّلاع على الأسئلة الشائعة حول "خرائط Google" لمزيد من المعلومات حول كيفية حلّ هذا الخطأ.
REQUEST_DENIED يشير إلى أنّه تم رفض طلبك، وذلك عادةً بسبب:
- لا يتضمّن الطلب مفتاح واجهة برمجة التطبيقات.
- المَعلمة key غير صالحة.
‫UNKNOWN_ERROR تشير إلى حدوث خطأ غير معروف.

المكان

تعرض ردود "البحث عن الأماكن" المجموعة الفرعية التالية من حقول المكان. لا تتوفّر بعض السمات لبعض أنواع الأماكن. لاسترداد الحقول التي لا تعرضها ميزة "البحث عن الأماكن"، مثل address_components أو formatted_phone_number أو reviews أو website، مرِّر place_id المعروض في طلب تفاصيل المكان (القديم). للاطّلاع على مدى توفّر الحقول وفئات الأسعار في جميع نقاط النهاية، يُرجى مراجعة حقول بيانات الأماكن (القديمة).

الحقل	النوع	الوصف
`business_status`	`string`	تشير إلى حالة عمل المكان، إذا كان نشاطًا تجاريًا: `OPERATIONAL` أو `CLOSED_TEMPORARILY` أو `CLOSED_PERMANENTLY`. يتم حذفها في حال عدم توفّر بيانات الحالة.
`formatted_address`	`string`	العنوان الذي يمكن لشخص عادي قراءته لهذا المكان يتم عرض هذا الحقل من خلال "البحث النصي (الإصدار القديم)" و"العثور على مكان (الإصدار القديم)". لا تحلّل العنوان المنسَّق برمجيًا، بل اطلب `address_components` في تفاصيل المكان (الإصدار القديم) بدلاً من ذلك.
`geometry`	`Geometry`	يحتوي على `location` المرمّز جغرافيًا مع إحداثيات `lat` و`lng`، و`viewport` المفضّل مع حدود `northeast` و`southwest`.
`icon`	`string`	عنوان URL لرمز مقترَح يمكنك عرضه عند الإشارة إلى هذه النتيجة على خريطة
`icon_background_color`	`string`	رمز اللون الست عشري التلقائي لفئة المكان
`icon_mask_base_uri`	`string`	الجزء الأساسي من عنوان URL لرمز مقترَح، بدون امتداد نوع الملف SVG أو PNG
`name`	`string`	الاسم الذي يمكن لشخص عادي قراءته للنتيجة المعروضة بالنسبة إلى نتائج `establishment`، تكون هذه القيمة عادةً اسم النشاط التجاري الذي تم تحديده كنسخة أساسية.
`opening_hours`	`PlaceOpeningHours`	معلومات ساعات العمل تعرض نقاط نهاية "البحث عن الأماكن" الحقل الفرعي المنطقي `open_now` فقط. يمكنك طلب `opening_hours` في "تفاصيل المكان" (الإصدار القديم) للحصول على `periods` و`weekday_text`.
`permanently_closed`	`boolean`	متوقّفة نهائيًا: استخدِم السمة `business_status` للتحقّق من حالة التشغيل لنشاط تجاري.
`photos`	`Array<PlacePhoto>`	تمثّل هذه السمة مصفوفة من عناصر `PlacePhoto`، ويحتوي كل عنصر على `photo_reference` و`height` و`width` و`html_attributions`. للاطّلاع على تفاصيل الاستخدام، يُرجى مراجعة صور الأماكن (الإصدار القديم).
`place_id`	`string`	معرّف نصي يحدّد مكانًا بشكل فريد مرِّر رقم التعريف هذا في المَعلمة `place_id` لطلب تفاصيل المكان (القديم). اطّلِع على نظرة عامة على رقم تعريف المكان.
`plus_code`	`PlusCode`	مرجع موقع جغرافي مرمّز مشتق من إحداثيات خطوط العرض والطول، ويحتوي على `global_code` و`compound_code` اختياري.
`price_level`	`integer`	مستوى سعر المكان على مقياس من `0` إلى `4`، من الأقل تكلفة إلى الأعلى تكلفة يمكنك الاطّلاع على `price_level`.
`rating`	`number`	يشير هذا الحقل إلى تقييم المكان، من `1.0` إلى `5.0`، استنادًا إلى مراجعات المستخدمين المجمّعة.
`reference`	`string`	تم إيقافها نهائيًا: يُرجى استخدام `place_id` بدلاً منها.
`scope`	`string`	متوقّفة نهائيًا: تشير إلى نطاق `place_id`، وهو دائمًا `GOOGLE`. يتم عرضها من خلال "بحث في الجوار (الإصدار القديم)".
`types`	`Array<string>`	مصفوفة من أنواع الميزات التي تصف النتيجة المحدّدة راجِع أنواع الأماكن (القديمة).
`user_ratings_total`	`integer`	تمثّل هذه السمة إجمالي عدد التقييمات لهذا المكان، سواء كانت تتضمّن نص مراجعة أم لا.
`vicinity`	`string`	عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقم الشارع والمنطقة، بدون الولاية أو المقاطعة أو الرمز البريدي أو البلد يتم عرضها من خلال خدمة "بحث في الجوار (الإصدار القديم)".

العثور على مكان (الإصدار القديم)

طلبات Find Place (Legacy)

المعلمات المطلوبة

إدخال

inputtype

المعلمات الاختيارية

fields

language

locationbias

أمثلة على Find Place (الإصدار القديم)

curl

HTTP

curl

HTTP

curl

HTTP

استجابات Find Place (Legacy)

JSON

XML

PlacesFindPlaceFromTextResponse

`candidates`

`status`

`error_message`

`info_messages`

PlacesSearchStatus

المكان

العثور على مكان (الإصدار القديم) تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

طلبات Find Place (Legacy)

المعلمات المطلوبة

إدخال

inputtype

المعلمات الاختيارية

fields

language

locationbias

أمثلة على Find Place (الإصدار القديم)

curl

HTTP

curl

HTTP

curl

HTTP

استجابات Find Place (Legacy)

JSON

XML

PlacesFindPlaceFromTextResponse

candidates

status

error_message

info_messages

PlacesSearchStatus

المكان

العثور على مكان (الإصدار القديم)

`candidates`

`status`

`error_message`

`info_messages`