بدء استخدام Geocoding API الإصدار 4

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

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

أمثلة على الطلبات والردود

يمكنك الوصول إلى Geocoding API من خلال واجهة HTTP. في ما يلي أمثلة للبدء السريع على البحث عن الوجهات والترميز الجغرافي الأمامي وعكس الترميز الجغرافي.

طلب البحث عن الوجهات والردّ عليه (بيانات الوصول على مستوى منطقة محلية صغيرة)

يرسل المثال التالي طلب HTTP POST إلى SearchDestinations للحصول على "1600 Amphitheatre Parkway, Mountain View, CA". يُرجى العِلم أنّ SearchDestinations يتطلّب عنوان X-Goog-FieldMask يحدّد الحقول المطلوب عرضها:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA"
  }
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/destinations"

في ما يلي نموذج لردّ من SearchDestinations يعرض المضلّع الخاص بمساحة المبنى والمداخل المفضّلة ونقاط التنقّل القابلة للتوجيه والمعالم القريبة:

{
  "destinations": [
    {
      "primary": {
        "displayName": { "text": "Googleplex", "languageCode": "en" },
        "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
        "location": { "latitude": 37.4220656, "longitude": -122.0840897 },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [-122.084958, 37.422145],
              [-122.084112, 37.422610],
              [-122.083510, 37.421980],
              [-122.084958, 37.422145]
            ]
          ]
        }
      },
      "entrances": [
        {
          "location": { "latitude": 37.422189, "longitude": -122.084215 },
          "tags": ["PREFERRED"]
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "Eg...",
          "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" },
          "location": { "latitude": 37.421912, "longitude": -122.084301 },
          "travelModes": ["DRIVE"],
          "usages": ["DROPOFF", "PICKUP"]
        }
      ],
      "landmarks": [
        {
          "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } },
          "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" },
          "straightLineDistanceMeters": 85.4
        }
      ]
    }
  ]
}

طلب الترميز الجغرافي والاستجابة له (البحث عن خطوط العرض/الطول)

يطلب المثال التالي خط العرض وخط الطول لـ "1600 Amphitheatre Parkway, Mountain View, CA"، ويحدّد أن يكون الناتج بتنسيق JSON.

curl -H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

يمكنك اختبار ذلك من خلال إدخال عنوان URL في متصفّح الويب (تأكَّد من استبدال YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الفعلي). يتضمّن الردّ خط العرض وخط الطول للعنوان.

يمكنك الاطّلاع على دليل المطوّر لمزيد من المعلومات حول إنشاء عناوين URL لطلبات الترميز الجغرافي، والمَعلمات المتاحة و فهم الردّ.

في ما يلي نموذج لردّ الترميز الجغرافي بتنسيق JSON:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "location": {
        "latitude": 37.4438238,
        "longitude": -122.0869895
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4424748197085,
          "longitude": -122.0883384802915
        },
        "high": {
          "latitude": 37.445172780291493,
          "longitude": -122.08564051970852
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

طلب عكس الترميز الجغرافي والاستجابة له (البحث عن العنوان)

يطلب المثال التالي العنوان المقابل لخط عرض/خط طول معيّن في بروكلين، نيويورك، الولايات المتحدة الأمريكية. ويحدّد أنّ الناتج يجب أن يكون بتنسيق JSON.

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=YOUR_API_KEY

يمكنك اختبار ذلك عن طريق إدخال عنوان URL في متصفّح الويب (تأكَّد من استبدال "YOUR_API_KEY" بمفتاح واجهة برمجة التطبيقات الفعلي). يتضمّن الردّ عنوانًا يمكن لشخص عادي قراءته لموقع خطوط العرض والطول.

يمكنك الاطّلاع على دليل المطوّر لمزيد من المعلومات حول إنشاء عناوين URL لطلبات عكس الترميز الجغرافي والمَعلمات المتاحة و فهم الاستجابة.

في ما يلي نموذج لردّ عكس الترميز الجغرافي بتنسيق JSON:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "location": {
        "latitude": 37.4225657,
        "longitude": -122.08465439999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421214719708509,
          "longitude": -122.08603273029148
        },
        "high": {
          "latitude": 37.423912680291508,
          "longitude": -122.0833347697085
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4225178,
          "longitude": -122.08484599999998
        },
        "high": {
          "latitude": 37.422609600000008,
          "longitude": -122.0845215
        }
      },
      "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "Google Building 40",
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 40",
          "shortText": "Google Building 40",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address",
        "subpremise"
      ]
    },
    ... Additional results truncated in this example[] ...
}

المصادقة والحصص والأسعار والسياسات

المصادقة

لاستخدام Geocoding API، عليك أولاً تفعيل واجهة برمجة التطبيقات والحصول على بيانات اعتماد المصادقة المناسبة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة بدء استخدام "منصة خرائط Google".

الحصص والأسعار

راجِع صفحة الاستخدام والفوترة للاطّلاع على تفاصيل حول الحصص والأسعار المحدّدة لواجهة Geocoding API.

السياسات

يجب أن يكون استخدام Geocoding API متوافقًا مع سياسات واجهة برمجة التطبيقات.