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

اختيار النظام الأساسي: 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 للحصول على 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