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

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

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

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

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

استخدام Places API

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

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

تعرض خريطة المثال هذه كيفية إرسال طلب 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

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

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

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

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

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

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

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

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

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

تستدعي دالة المثال التالية 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 تحويل العناوين إلى إحداثيات جغرافية والعكس. تتكامل الاستخدامات التالية بشكل جيد مع التنسيق المستند إلى البيانات للحدود:

  • استخدِم الترميز الجغرافي للحصول على إطار العرض لمنطقة معيّنة.
  • طبِّق فلترة المكوّنات على طلب Geocoding للحصول على معرّفات الأماكن الخاصة بالمناطق الإدارية من 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)
        });
}

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

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

// 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
```