البحث عن الوجهات

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

A Destination تشير إلى موقع أو مكان محدّدَين يعتزم المستخدم الوصول إليهما أو التنقّل نحوهما. يتضمّن Destination أيضًا مجموعة من المعلومات ذات الصلة بـ الموقع أو المكان، مثل نقاط التنقّل والمعالم والواجهات و مخططات المباني.

تتيح لكم طريقة SearchDestinations في Geocoding API استرداد معلومات مفصّلة عن وجهات مختلفة استنادًا إلى معايير إدخال مختلفة، مثل العنوان أو رقم تعريف المكان أو إحداثيات خط العرض وخط الطول.

طلب البحث عن الوجهات

طلب البحث عن الوجهات طلب هو طلب HTTP POST إلى عنوان URL بالتنسيق التالي:

https://geocode.googleapis.com/v4/geocode/destinations

يجب تمرير جميع المَعلمات في نص طلب JSON أو في العناوين كجزء من طلب POST. على سبيل المثال:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

يمكنكم تحديد الموقع الجغرافي للبحث عن وجهة بإحدى الطرق الثلاث التالية:

  • العنوان
  • معرّف المكان
  • إحداثيات خطوط العرض وخطوط الطول

البحث عن وجهة حسب العنوان

يمكنكم تحديد العنوان كسلسلة غير منظَّمة. لا يحلّ الترميز الجغرافي للعنوان إحداثيات خطوط العرض والطول أو السلاسل غير المنظَّمة الأخرى التي لا تمثّل عنوانًا. لا تتوافق الطلبات التي تستخدم مثل هذه السلاسل وقد تؤدي إلى ظهور ردود تتضمّن أخطاء أو سلوك غير محدّد. في ما يلي أمثلة على طلبات البحث غير المتوافقة:

نوع طلب البحث مثال
إحداثيات خطوط العرض وخطوط الطول. يُرجى استخدام طلب بحث عن موقع جغرافي بدلاً من ذلك. "37.422131,-122.084801"
عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعدّدة في طلب بحث واحد "Market Street San Francisco San Jose Airport"
عناصر العنوان البريدي غير الممثّلة على "خرائط Google" "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
أسماء المؤسسات أو السلاسل أو الفئات المدمَجة مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات "Tesco near Dallas, Texas"
طلبات البحث الغامضة التي تتضمّن تفسيرات متعدّدة "Charger drop-off"
الأسماء القديمة التي لم تعُد مستخدَمة "Middlesex United Kingdom"
العناصر أو النية غير الجغرافية المكانية "How many boats are in Ventura Harbor?"
الأسماء غير الرسمية أو الأسماء التي تم اختيارها لجذب الانتباه "The Jenga"
"The Helter Skelter"
الكيانات السياسية الكبيرة (المدن والولايات والبلدان) "New York City"
"California"
"USA"
الطرق بدون عناوين محدّدة "1st Ave., NYC, NY"
"I-95" 
curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

أو بتنسيق postalAddress:

curl -X POST -d '{
  "addressQuery": {
    "address": {
      "addressLines": ["601 S Bernardo Ave"],
      "locality": "Sunnyvale",
      "postalCode": "94087",
      "administrativeArea": "CA",
      "regionCode": "US"
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

يتم عادةً استخدام تنسيق postalAddress عند معالجة مكوّنات العنوان التي يتم التقاطها في نموذج HTML.

البحث عن وجهة حسب رقم تعريف المكان

يمكنكم استرداد وجهة من خلال تقديم رقم تعريف المكان:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

أرقام تعريف الأماكن المتوافقة

تعمل طريقة "البحث عن الوجهات" على أفضل نحو مع أرقام تعريف الأماكن التي تمثّل وجهات محدّدة وقابلة للتنقّل. تكون أرقام تعريف الأماكن لأنواع مثل establishment, point_of_interest, premise, street_address, وsubpremise متوافقة بشكل عام. أرقام تعريف الأماكن التي لا تمثّل مواقع منفصلة، مثل تلك المستنتَجة من نطاقات العناوين (على سبيل المثال، "10-20 Main St") أو أقسام الطريق بدون رقم محدّد أو رموز Plus Codes، غير متوافقة. كما أنّ أرقام تعريف الأماكن للنتائج التي تكون مساحتها كبيرة جدًا (على سبيل المثال، "المحيط الهادئ") غير متوافقة أيضًا.

استخدام ميزة "الإكمال التلقائي (الجديدة)" مع طريقة "البحث عن الوجهات"

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

"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]

بالإضافة إلى ذلك، يجب عدم ضبط include_pure_service_area_businesses العلامة على true في طلب ميزة "الإكمال التلقائي (الجديدة)".

البحث عن وجهة حسب الموقع الجغرافي

يمكنكم البحث عن وجهة من خلال تقديم إحداثيات خط العرض وخط الطول:

curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

استخدام بروتوكول OAuth لتقديم طلب

يتوافق Geocoding API v4 مع بروتوكول OAuth 2.0 للمصادقة. لاستخدام بروتوكول OAuth مع Geocoding API، يجب منح رمز OAuth النطاق الصحيح. يتوافق Geocoding API مع النطاقات التالية لاستخدامها مع طريقة "الوجهات":

  • https://www.googleapis.com/auth/maps-platform.geocode : يمكن استخدام هذا النطاق مع جميع طرق Geocoding API.

يمكنكم أيضًا استخدام النطاق العام https://www.googleapis.com/auth/cloud-platform لجميع طرق Geocoding API. يكون هذا النطاق مفيدًا أثناء التطوير، ولكن ليس في مرحلة الإنتاج، لأنّه نطاق عام يتيح الوصول إلى جميع الطرق.

لمزيد من المعلومات والأمثلة، يُرجى الاطّلاع على مقالة استخدام بروتوكول OAuth.

الرد على طلب البحث عن الوجهات

يقدّم الرد على طلب "البحث عن الوجهات" سياقًا غنيًا وعلى مستوى منطقة محلية صغيرة حول الموقع الجغرافي.

تستخدم كائنات PlaceView ضِمن الرد على طلب "البحث عن الوجهات" (مثل primary والعناصر في containingPlaces وlandmarks) حقولاً للإشارة إلى نوع المكان:

  • types: مصفوفة من السلاسل تشير إلى أنواع المكان.
  • primaryType: سلسلة تشير إلى النوع الأساسي للمكان.

يتم استخلاص قيم السلاسل المحتمَلة لكل من types وprimaryType من الجدولَين "أ" و"ب" في صفحة أنواع الأماكن (الجديدة).

يصف هذا القسم حقول الرد الرئيسية. للاطّلاع على التفاصيل الكاملة عن جميع حقول الرد، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات.

primary

المكان الرئيسي الذي حدّده طلب البحث في الطلب.

addressComponents

مصفوفة تحتوي على المكوّنات المنفصلة التي تنطبق على هذا العنوان.

يحتوي كل مكوّن من مكوّنات العنوان عادةً على الحقول التالية:

  • types[] هي مصفوفة تشير إلى نوع مكوّن العنوان. اطّلِعوا على قائمة الأنواع المتوافقة.
  • longText هو الوصف النصي الكامل أو اسم مكوّن العنوان كما يعرضه برنامج الترميز الجغرافي.
  • shortText هو اسم نصي مختصر لمكوّن العنوان، إذا كان متوفرًا. على سبيل المثال، قد يكون لمكوّن العنوان الخاص بولاية ألاسكا longText بقيمة "Alaska" وshortText بقيمة "AK" باستخدام الاختصار البريدي المكوّن من حرفَين.
  • languageCode هي اللغة المستخدَمة لتنسيق هذا المكوّن، بتنسيق CLDR.

containingPlaces

الكيانات الأكبر التي تشكّل الوجهة الرئيسية جزءًا منها (على سبيل المثال، مركز تسوّق يحتوي على متجر)

subDestinations

المواقع الأكثر تحديدًا ضِمن الوجهة الرئيسية (على سبيل المثال، الشقق في مبنى)

entrances

تحتوي الكائنات في مصفوفة entrances[] على الحقول التالية:

  • location

    زوج إحداثيات خط العرض وخط الطول يحدّد موقع نقطة الدخول والخروج إلى مكان

  • entrance_tags[]

    مصفوفة من علامات الدخول التي تصف خصائص المدخل القيمة التالية متوافقة:

    • "PREFERRED"

    تشير إلى أنّ هذا المدخل من المحتمل أن يوفّر وصولاً فعليًا إلى المكان الذي تم عرضه. يمكن أن يكون للمكان مداخل مفضّلة متعدّدة. إذا لم يكن للمدخل هذه العلامة، يعني ذلك أنّ المدخل يقع فعليًا في المبنى نفسه ولكنّه لا يوفّر بالضرورة وصولاً إلى المكان.

    على سبيل المثال، إذا كان المكان الذي تم عرضه هو مطعم في مركز تجاري، ستكون المداخل التي تحمل العلامة "PREFERRED" هي تلك التي تؤدي إلى المطعم نفسه، بينما ستكون المداخل الأخرى التي تم عرضها هي مداخل أخرى للمبنى، مثل المداخل إلى المطاعم الأخرى في المركز التجاري.

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

  • streetViewThumbnail وstreetViewAnnotation

    مَعلمات Street View Static API، ما يتيح لكم عرض صور ذات صلة بهذه المواقع مزيد من المعلومات حول هذه الحقول.

structureType

نوع الهيكل الذي يمثّله هذا المكان

  • POINT

    موقع جغرافي نقطي

  • SECTION

    قسم فرعي من مبنى

  • BUILDING

    مبنى

  • GROUNDS

    منطقة كبيرة تحتوي عادةً على مبانٍ متعدّدة، مثل حرم جامعي أو مجمّع سكني أو مركز تسوّق

يحتوي الحقل navigationPoints ضِمن استجابة Geocoding على قائمة بالنقاط المفيدة للتنقّل إلى المكان. على وجه التحديد، يجب استخدامها كنقاط بداية أو نهاية عند توجيه المسار على شبكة الطرق من المكان أو إليه.

تحتوي كل نقطة تنقّل على القيم التالية:

  • navigationPointToken هو رمز مميّز يحتوي على المعلومات السياقية في الحقل navigationPoints. يمكنكم إرسال هذا الرمز المميّز إلى واجهات برمجة التطبيقات للتوجيه والتنقل لتحسين تجربة التوجيه والتنقل في تطبيقكم. يُرجى الاطّلاع على مقالةتوجيه المسار باستخدام الرموز المميّزة لنقاط التنقّللمزيد من المعلومات.
  • location يحتوي على قيمة خط العرض وخط الطول لنقطة التنقّل. سيكون هذا الموقع الجغرافي دائمًا قريبًا جدًا من شبكة الطرق ويمثّل نقطة توقف أو بداية مثالية للتنقّل من مكان وإليه. تم إزاحة النقطة قليلاً عن خط المنتصف للطريق بشكل متعمّد لوضع علامة واضحة على جانب الطريق الذي يقع فيه المكان.
  • travelModes هي قائمة بوسائل النقل التي يمكن الوصول إليها من نقطة التنقّل:
    • "DRIVE" هي وسيلة النقل التي تتوافق مع اتجاهات القيادة.
    • "WALK" هي وسيلة النقل التي تتوافق مع اتجاهات المشي.
  • usages هي قائمة بالاستخدامات التي تتيحها نقطة التنقّل. يمكن أن تكون الاستخدامات:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

بالنسبة إلى عمليات الاستلام والتوصيل، استخدِموا نقطة التنقّل التي تكون فيها وسيلة النقل DRIVE والاستخدام PICKUP أو DROPOFF. إذا لم تتوفّر نقاط الاستلام أو التوصيل، استخدِموا نقطة التنقّل الرئيسية للقيادة.

  • altitude_meters يحتوي على ارتفاع نقطة التنقّل بالأمتار بالنسبة إلى القطع الناقص WGS-84. في الحالات التي تكون فيها أجزاء الطريق مكدّسة عموديًا، استخدِموا الحقل altitude_meters لاختيار أفضل جزء من الطريق للتنقّل إليه في نظامكم.

landmarks

الأماكن المجاورة البارزة لمساعدة المستخدمين في فهم محيط الوجهة

arrivalSummary

معلومات مفيدة مستندة إلى الذكاء الاصطناعي للمساعدة في الوصول يُرجى الاطّلاع على الملخّصات المستندة إلى الذكاء الاصطناعي.

parkingOptions

معلومات مفصّلة عن مواقف السيارات

تنسيق الردّ

تعرض طريقة SearchDestinations استجابة SearchDestinationsResponse بتنسيق JSON التالي:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "meal_takeaway",
          "food_delivery",
          "american_restaurant",
          "restaurant",
          "food_store",
          "store",
          "food",
          "point_of_interest",
          "establishment"
        ],
        "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA",
        "postalAddress": {
          "regionCode": "US",
          "languageCode": "en",
          "postalCode": "94087",
          "administrativeArea": "CA",
          "locality": "Sunnyvale",
          "addressLines": [
            "601 S Bernardo Ave"
          ]
        },
        "structureType": "BUILDING",
        "location": {
          "latitude": 37.3734545,
          "longitude": -122.05693269999998
        },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.056930138027,
                37.3735253692531
              ],
              [
                -122.056960139391,
                37.3735372663597
              ],
              [
                -122.056994129366,
                37.3734828786847
              ],
              [
                -122.056969677395,
                37.3734731161089
              ],
              [
                -122.057061762447,
                37.3733261309656
              ],
              [
                -122.056979388817,
                37.3732935577128
              ],
              [
                -122.056798860285,
                37.3735818838642
              ],
              [
                -122.056875858081,
                37.3736121235316
              ],
              [
                -122.056930138027,
                37.3735253692531
              ]
            ]
          ]
        }
      },
      "containingPlaces": [
        {
          "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw",
          "displayName": {
            "text": "Cherry Chase Shopping Center",
            "languageCode": "en"
          },
          "primaryType": "shopping_mall",
          "types": [
            "shopping_mall",
            "point_of_interest",
            "establishment"
          ],
          "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA",
          "postalAddress": {
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94087-1020",
            "administrativeArea": "CA",
            "locality": "Sunnyvale",
            "addressLines": [
              "663 S Bernardo Ave"
            ]
          },
          "structureType": "GROUNDS",
          "location": {
            "latitude": 37.3731231,
            "longitude": -122.0578211
          },
          "displayPolygon": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  -122.057112227103,
                  37.3714618008523
                ],
                [
                  -122.057076849821,
                  37.3715743611411
                ],
                [
                  -122.056963607756,
                  37.3719081793948
                ],
                [
                  -122.056865279559,
                  37.3722026053835
                ],
                [
                  -122.056687872374,
                  37.3727258358476
                ],
                [
                  -122.056580005889,
                  37.3730511370747
                ],
                [
                  -122.056498845827,
                  37.3732994782583
                ],
                [
                  -122.056338259713,
                  37.3737878663325
                ],
                [
                  -122.056618678291,
                  37.373887693582
                ],
                [
                  -122.056912102521,
                  37.3740010327191
                ],
                [
                  -122.057532418159,
                  37.3742476426462
                ],
                [
                  -122.057673926626,
                  37.3742441740031
                ],
                [
                  -122.057735663106,
                  37.3742328516943
                ],
                [
                  -122.057766531332,
                  37.3742220604378
                ],
                [
                  -122.057797572967,
                  37.37420520725
                ],
                [
                  -122.057828267759,
                  37.3741852342085
                ],
                [
                  -122.058060299297,
                  37.3740060842535
                ],
                [
                  -122.058199726081,
                  37.3737861673422
                ],
                [
                  -122.05836707267,
                  37.373524542556
                ],
                [
                  -122.058569622393,
                  37.3732018598683
                ],
                [
                  -122.0587638478,
                  37.3728890198039
                ],
                [
                  -122.058934661823,
                  37.3726036257774
                ],
                [
                  -122.059164956851,
                  37.3722498383629
                ],
                [
                  -122.058997784906,
                  37.3721804442035
                ],
                [
                  -122.057936479838,
                  37.3717605636234
                ],
                [
                  -122.057495827092,
                  37.3715860151634
                ],
                [
                  -122.057112227103,
                  37.3714618008523
                ]
              ]
            ]
          }
        }
      ],
      "landmarks": [
        {
          "place": {
            "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg",
            "displayName": {
              "text": "Chase Bank",
              "languageCode": "en"
            },
            "primaryType": "bank",
            "types": [
              "bank",
              "atm",
              "finance",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1234 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.373579,
              "longitude": -122.05752700000001
            }
          },
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 61.182193756103516,
          "travelDistanceMeters": 63.075645446777344
        },
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "butcher_shop",
              "florist",
              "deli",
              "supermarket",
              "bakery",
              "food_delivery",
              "market",
              "manufacturer",
              "food_store",
              "store",
              "food",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "639 S Bernardo Ave"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3727912,
              "longitude": -122.0581172
            }
          },
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 158.65606689453125,
          "travelDistanceMeters": 131.1669921875
        },
        {
          "place": {
            "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk",
            "displayName": {
              "text": "Oil Changers",
              "languageCode": "en"
            },
            "types": [
              "car_repair",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1240 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743054,
              "longitude": -122.0584272
            }
          },
          "relationalDescription": {
            "text": "Down the road from Oil Changers",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL"
          ],
          "straightLineDistanceMeters": 140.52459716796875,
          "travelDistanceMeters": 143.24220275878906
        },
        {
          "place": {
            "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0",
            "displayName": {
              "text": "Apni Mandi Farmers Market Sunnyvale",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "cake_shop",
              "supermarket",
              "asian_grocery_store",
              "indian_restaurant",
              "meal_takeaway",
              "bakery",
              "manufacturer",
              "wholesaler",
              "restaurant",
              "food_store",
              "store",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1056",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1111 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3737199,
              "longitude": -122.0522958
            }
          },
          "relationalDescription": {
            "text": "Near Apni Mandi Farmers Market Sunnyvale",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 410.37435913085938,
          "travelDistanceMeters": 479.49893188476562
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "primaryType": "chicken_restaurant",
            "types": [
              "chicken_restaurant",
              "fast_food_restaurant",
              "restaurant",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1028",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1241 W El Camino Real"
              ]
            },
            "structureType": "BUILDING",
            "location": {
              "latitude": 37.3746764,
              "longitude": -122.05708860000001
            },
            "displayPolygon": {
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ],
              "type": "Polygon"
            }
          },
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 87.348007202148438,
          "travelDistanceMeters": 214.08084106445312
        }
      ],
      "entrances": [
        {
          "location": {
            "latitude": 37.3735328,
            "longitude": -122.05694879999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4",
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "PARKING"
          ]
        }
      ]
    }
  ]
}

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

  • يجب تضمين إحدى المَعلمات الثلاث التالية في طلب بيانات من واجهة برمجة التطبيقات، والتي تحدّد العنوان أو المكان أو الموقع الجغرافي للبحث عن وجهة:
    • addressQuery : العنوان المطلوب البحث عنه
    • place : رقم تعريف المكان المطلوب البحث عنه
    • locationQuery : إحداثيات خط العرض وخط الطول لـ الموقع الجغرافي المطلوب البحث عنه

  • FieldMask

    يجب تحديد قائمة الحقول المطلوب عرضها في الرد من خلال إنشاء قناع حقول الرد. يجب تمرير قناع حقول الرد إلى الطريقة باستخدام مَعلمة عنوان URL $fields أو fields أو باستخدام عنوان HTTP X-Goog-FieldMask. على سبيل المثال، لن يعرض الطلب أدناه سوى المداخل ونقاط التنقّل ورقم تعريف المكان للوجهة الرئيسية.

      curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
    -H "X-Goog-Api-Key: API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \
    https://geocode.googleapis.com/v4/geocode/destinations

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

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

  • travelModes

    يحدّد هذا الحقل أنواع navigationPoints المطلوب عرضها. وسيتم استبعاد نقاط التنقّل لوسائل النقل الأخرى. إذا لم يتم ضبط travelModes، يمكن عرض نقاط التنقّل لجميع وسائل النقل.

  • languageCode

    اللغة المطلوب عرض النتائج بها

    • اطّلِعوا على قائمة اللغات المتوافقة. تُحدّث Google اللغات المتوافقة بانتظام ، لذا قد لا تكون هذه القائمة شاملة.
    • إذا لم يتم تقديم languageCode، ستستخدم واجهة برمجة التطبيقات اللغة المحلية و البرنامج النصي للموقع الجغرافي تلقائيًا. إذا تم تحديد رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات خطأ INVALID_ARGUMENT.
    • تبذل واجهة برمجة التطبيقات قصارى جهدها لتقديم عنوان شارع يمكن قراءته لـ لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض واجهة برمجة التطبيقات عناوين الشوارع باللغة المحلية، مع نقلها حرفيًا إلى برنامج نصي يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. يتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
    • إذا لم يتوفّر اسم باللغة المفضّلة، ستستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابِقة.
    • تؤثر اللغة المفضّلة بشكل طفيف في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها والترتيب الذي يتم عرضها به. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة واحدة ولكن ليس في لغة أخرى.

  • regionCode

    رمز المنطقة كقيمة رمز CLDR مكوّنة من حرفَين لا توجد قيمة تلقائية. تتطابق معظم رموز CLDR مع رموز ISO 3166-1.

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

  • placeFilter

    تتيح لكم هذه المَعلمة فلترة نتائج البحث locationQuery لتلبية متطلباتكم، مثل عرض الوجهات التي هي مبانٍ فقط أو الوجهات التي لها عناوين واضحة فقط.

    الفلترة حسب الدقة الهيكلية

    يتيح لكم فلتر structureType تحديد نوع الهياكل التي يعرضها طلب البحث:

    • عزل المباني: استخدِموا "structureType": "BUILDING" لعرض مخططات المباني على الخريطة أو الحصول على تفاصيل لهيكل محدّد.
    • فهم المجمّعات: استخدِموا "structureType": "GROUNDS" لضمان أن تكون النتيجة الرئيسية هي المساحات الإجمالية. يكون هذا الخيار مفيدًا عند طلب البحث عن مناطق أكبر، مثل الحرم الجامعي أو مراكز التسوّق.
    • التركيز على الوحدات/الأقسام: استخدِموا "structureType": "SECTION" لتحديد الأقسام ضِمن مبنى.

    ضمان توفّر عناوين مفيدة

    لا تتوفّر عناوين واضحة على مستوى الشارع لبعض الأماكن. يساعدكم فلتر addressability في التحكّم في جودة العناوين في نتائجكم:

    • طلب عنوان أساسي واضح: لضمان أن تحتوي نتيجة الوجهة الرئيسية دائمًا على عنوان أو اسم على مستوى الشارع، استخدِموا "addressability": "PRIMARY". يكون هذا الخيار مفيدًا لأغراض التنقّل أو العرض حيث يكون العنوان الواضح ضروريًا.
    • السماح بالعناوين في الوجهات الفرعية: في الحالات التي قد لا يكون للمكان الرئيسي عنوان، ولكن الوحدات ضِمنه تحتوي على عناوين (مثل الشقق في مبنى)، يضمن "addressability": "WEAK" أن يكون للمكان الرئيسي أو إحدى وجهاته الفرعية عنوان على الأقل.
    • أي نتيجة: إذا لم يكن توفّر العنوان مهمًا لحالة الاستخدام، استخدِموا "addressability": "ANY". ننصح بشدة باستخدام هذا الخيار عندما تحتاجون فقط إلى سمات هندسية، مثل مخططات المباني ونقاط التنقّل، لأنّه يحسّن دقة هذه النتائج.
    مثال: فلترة المباني التي يمكن تحديد عنوان لها 
    curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4/geocode/destinations