This product or feature is in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions.

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

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

تشير Destination إلى نقطة مهمة أو موقع جغرافي محدّد ينوي المستخدم الوصول إليه أو الانتقال نحوه. يمكن أن يتضمّن Destination معلومات مثل نقاط التنقّل والمعالم البارزة والمداخل ومخططات المباني.

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

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

طلب البحث عن وجهات هو طلب HTTP POST إلى عنوان URL بالصيغة التالية:

https://geocode.googleapis.com/v4alpha/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/v4alpha/geocode/destinations

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

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

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

يمكنك تحديد العنوان كسلسلة غير منظَّمة:

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/v4alpha/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/v4alpha/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/v4alpha/geocode/destinations

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

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

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/v4alpha/geocode/destinations

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

تتيح الإصدار 4 من Geocoding API استخدام OAuth 2.0 للمصادقة. لاستخدام OAuth مع Geocoding API، يجب منح رمز OAuth المميز النطاق الصحيح. تتيح Geocoding API النطاقات التالية لاستخدامها مع نقطة النهاية Destinations:

https://www.googleapis.com/auth/maps-platform.geocode — تُستخدَم مع جميع نقاط نهاية Geocoding API.

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

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

ردّ البحث في الوجهات

معلومات محلية دقيقة حول الموقع الجغرافي

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

‫primary: المكان الرئيسي الذي يحدّده طلب البحث في الطلب.
‫containingPlaces: تشير إلى المؤسسات الأكبر التي تشكّل الوجهة الأساسية جزءًا منها (على سبيل المثال، مركز تسوّق يضم متجرًا).
استبدِل subDestinations بمواقع جغرافية أكثر تحديدًا ضمن الوجهة الأساسية (مثل شقق في مبنى).
‫entrances: تمثّل نقاط الدخول والخروج المحدّدة للوجهة.
‫navigationPoints: مواقع مناسبة بالقرب من طريق معيّن للتنقّل إلى النهاية
‫arrivalSummary: إحصاءات مستندة إلى الذكاء الاصطناعي للمساعدة في الوصول إلى الوجهة اطّلِع على الملخّصات المستندة إلى الذكاء الاصطناعي.
‫landmarks: أماكن بارزة قريبة لمساعدة المستخدمين في فهم محيط الوجهة

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

تنسيق الردّ

تعرض SearchDestinations SearchDestinationsResponse بالتنسيق التالي:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "american_restaurant",
          "meal_takeaway",
          "restaurant",
          "food_store",
          "food",
          "point_of_interest",
          "store",
          "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/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "florist",
              "butcher_shop",
              "deli",
              "bakery",
              "food_delivery",
              "supermarket",
              "market",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "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
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 158.65607,
          "travelDistanceMeters": 131.16699
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "types": [
              "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": { ... }
 {
              "type": "Polygon",
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ]
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 87.34801,
          "travelDistanceMeters": 214.08084
        },
        {
          "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
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 61.182194,
          "travelDistanceMeters": 63.075645
        },
        {
          "place": {
            "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk",
            "displayName": {
              "text": "Madras Café",
              "languageCode": "en"
            },
            "primaryType": "indian_restaurant",
            "types": [
              "indian_restaurant",
              "coffee_shop",
              "cafe",
              "restaurant",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "establishment"
            ],
            "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1026",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1177 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743,
              "longitude": -122.0549333
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Madras Café",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 204.45102,
          "travelDistanceMeters": 235.12041
        }
      ],
      "entrances": [
        {
          "location": {
            "latitude": 37.373531299999996,
            "longitude": -122.05694519999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "UNKNOWN"
          ]
        }
      ]
    }
  ]
}

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

يجب أن تتضمّن طلبات البيانات من واجهة برمجة التطبيقات إحدى المَعلمات الثلاث التالية التي تحدّد العنوان أو المكان أو الموقع الجغرافي الذي سيتم البحث فيه عن وجهة:
- 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/v4alpha/geocode/destinations
  
```
لا توجد قائمة تلقائية بالحقول التي يتم عرضها في الردّ. إذا حذفت قناع الحقل، ستعرض الطريقة رسالة خطأ. اضبط قناع الحقل على * لعرض جميع الحقول. راجِع مقالة اختيار الحقول التي سيتم عرضها لمزيد من التفاصيل.

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

travelModes

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

اللغة التي سيتم عرض النتائج بها
- اطّلِع على قائمة اللغات المتاحة. تعدّل Google اللغات المتوافقة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
- إذا لم يتم توفير languageCode، تضبط واجهة برمجة التطبيقات القيمة التلقائية على en. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأ 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/v4alpha/geocode/destinations
```

الملاحظات

هذه نقطة نهاية تجريبية لواجهة Geocoding API. يسرّنا تلقّي ملاحظاتك على geocoding-feedback-channel@google.com.

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

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

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

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

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

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

ردّ البحث في الوجهات

معلومات محلية دقيقة حول الموقع الجغرافي

تنسيق الردّ

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

الفلترة حسب مستوى التفاصيل البنيوية

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

الملاحظات

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