استخدام Places APIs وGeocoding مع تنسيق مستند إلى البيانات للحدود

اختيار النظام الأساسي: Android iOS JavaScript

يمكنك استخدام Places API وGeocoding API في Maps JavaScript API للبحث عن المناطق والحصول على المزيد من المعلومات عن الأماكن. إنّ واجهتَي برمجة التطبيقات Geocoding API و Places API هما بديلان فعّالان ومستقران للحصول على أرقام تعريف المواقع الجغرافية. إذا كنت تستخدم أرقام تعريف الأماكن، يمكنك إعادة استخدام هذه الأرقام بسهولة مع استخدام أسلوب مستنِد إلى البيانات للحدود.

يمكنك إضافة Places وGeocoding إلى تطبيقات Maps JavaScript API بالطُرق التالية:

• مكتبة الأماكن، واجهة برمجة التطبيقات JavaScript لخرائط Google: تتيح لتطبيقك البحث عن الأماكن، وتتضمّن أداة إكمال تلقائي.
• تعرض Places API معلومات عن الأماكن باستخدام طلبات HTTP.
• يمكن لخدمة الترميز الجغرافي وفئة الترميز الجغرافي الترميز الجغرافي وعكس الترميز الجغرافي بشكل ديناميكي من إدخال المستخدم.
• تتيح لك واجهة برمجة التطبيقات Geocoding API ترميز المواقع الجغرافية للعناوين الثابتة المعروفة.

ملاحظة: يجب تفعيل Geocoding API Places API وPlaces API (الإصدار الجديد) (لميزة البحث النصي (الإصدار الجديد))، ويتم تحصيل رسوم استخدامها بشكل منفصل عن واجهة برمجة التطبيقات Maps JavaScript API.

استخدام Places API

استخدام ميزة "البحث عن نص" (جديد) للعثور على منطقة

يمكنك استخدام البحث النصي (جديد) للحصول على معرّف مكان يتضمّن بيانات المنطقة باستخدام includedType لتحديد نوع المنطقة المراد عرضها. لن يتم تحصيل أي رسوم مقابل استخدام Text Search (New) API لطلب معرّفات الأماكن فقط. مزيد من المعلومات

يوضّح مثال الخريطة هذا تقديم طلب searchByText للحصول على رمز تعريف مكان مدينة ترينيداد، كاليفورنيا، ثم تطبيق نمط على الحدود:

TypeScript

async function findBoundary() {
    const request = {
        query: 'Trinidad, CA',
        fields: ['id', 'location'],
        includedType: 'locality',
        locationBias: center,
    };

    const { Place } = await google.maps.importLibrary("places") as google.maps.PlacesLibrary;
    //@ts-ignore
    const { places } = await Place.searchByText(request);

    if (places.length) {
        const place = places[0];
        styleBoundary(place.id);
        map.setCenter(place.location);
    } else {
        console.log('No results');
    }
}

function styleBoundary(placeid) {
    // Define a style of transparent purple with opaque stroke.
    const styleFill = {
        strokeColor: '#810FCB',
        strokeOpacity: 1.0,
        strokeWeight: 3.0,
        fillColor: '#810FCB',
        fillOpacity: 0.5
    };

    // Define the feature style function.
    featureLayer.style = (params) => {
        if (params.feature.placeId == placeid) {
            return styleFill;
        }
    };
}
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

async function findBoundary() {
  const request = {
    query: "Trinidad, CA",
    fields: ["id", "location"],
    includedType: "locality",
    locationBias: center,
  };
  const { Place } = await google.maps.importLibrary("places");
  //@ts-ignore
  const { places } = await Place.searchByText(request);

  if (places.length) {
    const place = places[0];

    styleBoundary(place.id);
    map.setCenter(place.location);
  } else {
    console.log("No results");
  }
}

function styleBoundary(placeid) {
  // Define a style of transparent purple with opaque stroke.
  const styleFill = {
    strokeColor: "#810FCB",
    strokeOpacity: 1.0,
    strokeWeight: 3.0,
    fillColor: "#810FCB",
    fillOpacity: 0.5,
  };

  // Define the feature style function.
  featureLayer.style = (params) => {
    if (params.feature.placeId == placeid) {
      return styleFill;
    }
  };
}
index.js

الاطّلاع على رمز المصدر الكامل للمثال

TypeScript

let map;
let featureLayer;
let center;

async function initMap() {
    const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;

    center = {lat: 41.059, lng: -124.151}; // Trinidad, CA

    map = new Map(document.getElementById('map') as HTMLElement, {
        center: center,
        zoom: 15,
        // In the cloud console, configure this Map ID with a style that enables the
        // "Locality" Data Driven Styling type.
        mapId: 'a3efe1c035bad51b', // <YOUR_MAP_ID_HERE>,
    });

    featureLayer = map.getFeatureLayer('LOCALITY');

    findBoundary();
}
async function findBoundary() {
    const request = {
        query: 'Trinidad, CA',
        fields: ['id', 'location'],
        includedType: 'locality',
        locationBias: center,
    };

    const { Place } = await google.maps.importLibrary("places") as google.maps.PlacesLibrary;
    //@ts-ignore
    const { places } = await Place.searchByText(request);

    if (places.length) {
        const place = places[0];
        styleBoundary(place.id);
        map.setCenter(place.location);
    } else {
        console.log('No results');
    }
}

function styleBoundary(placeid) {
    // Define a style of transparent purple with opaque stroke.
    const styleFill = {
        strokeColor: '#810FCB',
        strokeOpacity: 1.0,
        strokeWeight: 3.0,
        fillColor: '#810FCB',
        fillOpacity: 0.5
    };

    // Define the feature style function.
    featureLayer.style = (params) => {
        if (params.feature.placeId == placeid) {
            return styleFill;
        }
    };
}
initMap();
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

let map;
let featureLayer;
let center;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  center = { lat: 41.059, lng: -124.151 }; // Trinidad, CA
  map = new Map(document.getElementById("map"), {
    center: center,
    zoom: 15,
    // In the cloud console, configure this Map ID with a style that enables the
    // "Locality" Data Driven Styling type.
    mapId: "a3efe1c035bad51b", // <YOUR_MAP_ID_HERE>,
  });
  featureLayer = map.getFeatureLayer("LOCALITY");
  findBoundary();
}

async function findBoundary() {
  const request = {
    query: "Trinidad, CA",
    fields: ["id", "location"],
    includedType: "locality",
    locationBias: center,
  };
  const { Place } = await google.maps.importLibrary("places");
  //@ts-ignore
  const { places } = await Place.searchByText(request);

  if (places.length) {
    const place = places[0];

    styleBoundary(place.id);
    map.setCenter(place.location);
  } else {
    console.log("No results");
  }
}

function styleBoundary(placeid) {
  // Define a style of transparent purple with opaque stroke.
  const styleFill = {
    strokeColor: "#810FCB",
    strokeOpacity: 1.0,
    strokeWeight: 3.0,
    fillColor: "#810FCB",
    fillOpacity: 0.5,
  };

  // Define the feature style function.
  featureLayer.style = (params) => {
    if (params.feature.placeId == placeid) {
      return styleFill;
    }
  };
}

initMap();
index.js

ملاحظة: خلال فترة الإصدار التجريبي، يمكنك إجراء 10 طلبات بحث كحد أقصى في الثانية لكل مشروع. مزيد من المعلومات

استخدام ميزة "الإكمال التلقائي للأماكن" للعثور على المناطق

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

// Set up the Autocomplete widget to return only region results.
const autocompleteOptions = {
  fields: ["place_id", "type"],
  strictBounds: false,
  types: ["(regions)"],
};

الحصول على تفاصيل الأماكن في منطقة معيّنة

يمكن أن تكون بيانات تفاصيل الأماكن في منطقة معيّنة مفيدة جدًا. يمكنك مثلاً:

• البحث عن أرقام تعريف الأماكن الحدودية استنادًا إلى أسماء الأماكن
• الحصول على إطار العرض للتكبير إلى حدود
• الحصول على نوع العنصر للحدود (على سبيل المثال locality)
• الحصول على العنوان المنسَّق الذي يُحلّ إلى "اسم المكان، الولاية، البلد" في منطقة الولايات المتحدة (على سبيل المثال، "أوتاوا، آيوا، الولايات المتحدة الأمريكية")
• الحصول على بيانات مفيدة أخرى، مثل الصور

يعثر مثال الدالة التالي على حدود ترينيداد، كاليفورنيا، ويركز الخريطة على النتيجة:

يستدعي المثال التالي للدالة fetchFields() للحصول على تفاصيل المكان بما في ذلك place.geometry.viewport، ثم يستدعي map.fitBounds() لتوسيط الخريطة على مضلع الحدود المحدّد.

    async function getPlaceDetails(placeId) {
        // Use place ID to create a new Place instance.
        const place = new google.maps.places.Place({
            id: placeId,
        });

        // Call fetchFields, passing the data fields you want.
        await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'geometry', 'type'] });

        // Zoom to the boundary polygon.
        let viewport = place.geometry.viewport;
        map.fitBounds(viewport, 155);

        // Print some place details to the console.
        const types = place.types;
        console.log("Feature type: " + types[0]);
        console.log("Formatted address: " + place.formattedAddress);
    }

استخدام واجهة برمجة التطبيقات Geocoding API

تتيح لك Geocoding API تحويل العناوين إلى إحداثيات جغرافية والعكس. تتوافق الاستخدامات التالية بشكل جيد مع التصميم المستنِد إلى البيانات للحدود:

• استخدِم الترميز الجغرافي للحصول على مساحة العرض لمنطقة معيّنة.
• طبِّق فلترة المكوّنات على طلب ترميز جغرافي للحصول على معرّفات الأماكن للمناطق الإدارية من 1 إلى 4 أو الرمز البريدي أو المنطقة.
• استخدِم الترميز الجغرافي العكسي للعثور على أرقام تعريف الأماكن حسب إحداثيات خط الطول/العرض، أو يمكنك حتى عرض أرقام تعريف الأماكن لجميع المكوّنات في موقع معيّن.

الحصول على إطار العرض لمنطقة معيّنة

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

// Set up the geocoder.
geocoder = new google.maps.Geocoder();

...

// Call Geocoding API and zoom to the resulting bounds.
function zoomToPolygon(placeid) {
    geocoder
        .geocode({ placeId: placeid })
        .then(({ results }) => {
            map.fitBounds(results[0].geometry.viewport, 155);
        })
        .catch((e) => {
            console.log('Geocoder failed due to: ' + e)
        });
}

استخدام ميزة عكس الترميز الجغرافي

يمكن استخدام ميزة عكس الترميز الجغرافي للعثور على معرّفات الأماكن. في المثال التالي، تعرض دالة Geocoding service أرقام تعريف الأماكن لجميع مكوّنات العنوان عند إحداثيات خط العرض/خط الطول المحدّدة:

// Set up the geocoder.
geocoder = new google.maps.Geocoder();

...

// Call Geocoding API.
function getPlaceIds(latLng) {
    geocoder
        .geocode({ latLng })
        .then(({ results }) => {
            console.log('Geocoding result:');
            console.log(results[0]);
            console.log(results[0].place_id);
            console.log(results[0].address_components);
        })
        .catch((e) => {
            console.log('Geocoder failed due to: ' + e)
        });
}

في ما يلي المكالمة المكافئة للخدمة على الويب لأجل عكس الترميز الجغرافي:

```html
https://maps.googleapis.com/maps/api/geocode/json?key="YOUR_API_KEY"&latlng=41.864182,-87.676930
```

لاستخدام ميزة ترميز المواقع الجغرافية العكسي مع فلترة المكوّنات للحصول على مكوّن العنوان لنوع واحد أو أكثر من الأنواع التالية في الموقع المحدّد:

• administrativeArea
• country
• locality
• postalCode

يعرض المثال التالي للدالة استخدام خدمة الترميز الجغرافي، مع إضافة قيود على المكونات باستخدام الترميز الجغرافي العكسي للحصول على جميع مكونات العنوان في الموقع المحدّد لنوع locality فقط:

// Set up the geocoder.
geocoder = new google.maps.Geocoder();

...

function getPlaceIdWithRestrictions(latLng) {
    geocoder
        .geocode({ latLng,
            componentRestrictions: {
              country: "US",
              locality: "chicago",
            },
        })
        .then(({ results }) => {
            console.log('Geocoding result with restriction:');
            console.log(results[0]);
            console.log(results[0].place_id);
            console.log(results[0].address_components);
            console.log(results[0].address_components[1].types[0]);
            console.log(results[0].address_components[1].long_name);
        })
        .catch((e) => {
            console.log('getPlaceId Geocoder failed due to: ' + e)
        });
}

في ما يلي طلب خدمة الويب المكافئ لعكس الترميز الجغرافي:

```html
    https://maps.googleapis.com/maps/api/geocode/json?key="YOUR_API_KEY"&latlng=41.864182,-87.676930&result_type=locality
```