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

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

طلبات 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 الشارع الرئيسي" أو "مبنى البلدية").

• inputtype

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

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

• fields

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

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

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

  الأساسية

  تتضمّن الفئة "الأساسية" الحقول التالية: 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.

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

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

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'

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

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

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'

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 -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'

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)

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

{
  "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 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

PlacesSearchStatus

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

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

المكان

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