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

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

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

أضف الأماكن والترميز الجغرافي إلى تطبيقات واجهة برمجة تطبيقات JavaScript للخرائط بالطرق التالية:

استخدام Places API

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

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

يوضح مثال الخريطة تقديم طلب 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

استخدام الإكمال التلقائي للأماكن للبحث عن المناطق

توفر أداة الإكمال التلقائي للأماكن طريقة ملائمة للسماح للمستخدمين بالبحث عن المناطق. لإعداد أداة الإكمال التلقائي للأماكن على عرض المناطق فقط، اضبط 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 desired data fields.
        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);
    }

استخدام واجهة برمجة تطبيقات الترميز الجغرافي

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

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

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

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)
        });
}

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

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