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

اختيار النظام الأساسي: 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) API لطلب أرقام تعريف الأماكن فقط. مزيد من المعلومات

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

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

استخدام واجهة برمجة التطبيقات 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)
        });
}

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

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