استفاده از «میانای برنامه‌سازی کاربردی مکان‌ها» و «زمین‌کدگذاری» با سبک‌دهی مبتنی بر داده برای مرزها

پلاتفرم را انتخاب کنید: Android iOS JavaScript

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

اگر نشانی صورت‌حساب شما در منطقه اقتصادی اروپا است، از ۸ ژوئیه ۲۰۲۵، شرایط خدمات «پلاتفرم Google Maps» در منطقه اقتصادی اروپا بر استفاده شما از «سرویس‌ها» اعمال خواهد شد. عملکرد بسته به منطقه متفاوت است. بیشتر بدانید.

می‌توانید از Places API و Geocoding API در Maps JavaScript API برای جستجوی مناطق و دریافت اطلاعات بیشتر درباره مکان‌ها استفاده کنید. Geocoding API و Places API جایگزین‌های قدرتمند و پایداری برای دریافت شناسه‌های جا هستند. اگر ازقبل از شناسه‌های مکان استفاده می‌کنید، به‌راحتی می‌توانید از آن شناسه‌ها با سبک‌بندی داده‌محور برای مرزها استفاده مجدد کنید.

«مکان‌ها» و «زمین‌کدیابی» را به روش‌های زیر به برنامه‌های Maps JavaScript API خود اضافه کنید:

• کتابخانه جاها، Maps JavaScript API، به برنامه شما امکان می‌دهد جاها را جستجو کند و شامل ابزاره تکمیل خودکار است.
• Places API اطلاعات مربوط به مکان‌ها را بااستفاده از درخواست‌های HTTP برمی‌گرداند.
• سرویس زمین‌کدیابی و کلاس زمین‌کدیاب می‌توانند به‌طور پویا از ورودی کاربر زمین‌کدیابی و زمین‌کدیابی معکوس انجام دهند.
• Geocoding API به شما امکان می‌دهد نشانی‌های ثابت و شناخته‌شده را زمین‌کدیابی کنید.

توجه: Geocoding API، Places API، و Places API (New) برای «جستجوی نوشتار» (جدید) باید فعال باشند و صورت‌حساب آن‌ها جدا از Maps JavaScript API صادر می‌شود.

استفاده از Places API

استفاده از «جستجوی نوشتار (جدید)» برای پیدا کردن منطقه

می‌توانید از جستجوی نوشتار (جدید) برای دریافت شناسه مکانی که شامل داده‌های منطقه است استفاده کنید. برای این کار، از includedType برای مشخص کردن نوع منطقه برای برگرداندن استفاده کنید. استفاده از Text Search (New) API برای درخواست شناسه‌های مکان فقط بدون هزینه خواهد بود. بیشتر بدانید.

این نقشه نمونه نحوه ارسال درخواست searchByText برای دریافت شناسه مکان برای ترینیداد، کالیفرنیا، و سپس اعمال سبک به مرز را نشان می‌دهد:

TypeScript

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

    const { Place } = await google.maps.importLibrary('places');
    const { places } = await Place.searchByText(request);

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

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

    // Define the feature style function.
    featureLayer.style = (params: google.maps.FeatureStyleFunctionOptions) => {
        const placeFeature = params.feature as google.maps.PlaceFeature;
        if (placeFeature.placeId === placeid) {
            return styleFill;
        }
        return null;
    };
}
index.ts

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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

    const { Place } = await google.maps.importLibrary('places');
    const { places } = await Place.searchByText(request);

    if (places.length) {
        const place = places[0];
        styleBoundary(place.id);
        innerMap.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) => {
        const placeFeature = params.feature;
        if (placeFeature.placeId === placeid) {
            return styleFill;
        }
        return null;
    };
}
index.js

مشاهده کد منبع نمونه کامل

TypeScript

let innerMap: google.maps.Map;
let featureLayer: google.maps.FeatureLayer;
let center: google.maps.LatLngLiteral;

async function init() {
    // Load the needed libraries.
    await google.maps.importLibrary('maps');

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

    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    innerMap = mapElement.innerMap;

    // Get the LOCALITY feature layer.
    featureLayer = innerMap.getFeatureLayer('LOCALITY');

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

    const { Place } = await google.maps.importLibrary('places');
    const { places } = await Place.searchByText(request);

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

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

    // Define the feature style function.
    featureLayer.style = (params: google.maps.FeatureStyleFunctionOptions) => {
        const placeFeature = params.feature as google.maps.PlaceFeature;
        if (placeFeature.placeId === placeid) {
            return styleFill;
        }
        return null;
    };
}
void init();
index.ts

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

let innerMap;
let featureLayer;
let center;

async function init() {
    // Load the needed libraries.
    await google.maps.importLibrary('maps');

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

    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    innerMap = mapElement.innerMap;

    // Get the LOCALITY feature layer.
    featureLayer = innerMap.getFeatureLayer('LOCALITY');

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

    const { Place } = await google.maps.importLibrary('places');
    const { places } = await Place.searchByText(request);

    if (places.length) {
        const place = places[0];
        styleBoundary(place.id);
        innerMap.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) => {
        const placeFeature = params.feature;
        if (placeFeature.placeId === placeid) {
            return styleFill;
        }
        return null;
    };
}
void init();
index.js

توجه: درطول انتشار «پیش‌نمایش»، شما محدود به انجام حداکثر ۱۰ پُرسمان در ثانیه برای هر پروژه هستید. بیشتر بدانید.

استفاده از «تکمیل خودکار جاها» برای یافتن مناطق

ابزاره «تکمیل خودکار جا» روشی راحت برای جستجوی مناطق توسط کاربران ارائه می‌دهد. برای پیکربندی ابزاره «تکمیل خودکار جا» برای برگرداندن فقط مناطق، includedPrimaryTypes را روی (regions) تنظیم کنید، همان‌طور که در قطعه کد زیر نشان داده شده است:

// Set up the Autocomplete widget to return only region results.
placeAutocomplete = document.querySelector(
    'gmp-place-autocomplete'
) as google.maps.places.PlaceAutocompleteElement;
placeAutocomplete.includedPrimaryTypes = ['(regions)'];

دریافت جزئیات جا برای یک منطقه

داده‌های جزئیات مکان برای یک منطقه می‌تواند بسیار مفید باشد. برای مثال، می‌توانید:

• شناسه‌های مکان مرزی را براساس نام مکان‌ها جستجو کنید.
• دریافت ناحیه نمایش برای بزرگ‌نمایی تا مرز.
• نوع عارضه را برای مرز دریافت کنید (برای مثال locality).
• نشانی قالب‌بندی‌شده را دریافت کنید که به «نام مکان، ایالت، کشور» در منطقه ایالات متحده تبدیل می‌شود (برای مثال، «Ottumwa, IA, USA»).
• داده‌های مفید دیگری مثل مرورها و عکس‌های کاربر را دریافت کنید.

تابع نمونه زیر مرز ترینیداد، کالیفرنیا را پیدا می‌کند و نقشه را روی نتیجه متمرکز می‌کند:

تابع نمونه زیر fetchFields() را فراخوانی می‌کند تا جزئیات جا را ازجمله place.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', 'viewport', 'types'] });

        // Zoom to the boundary polygon.
        let viewport = place.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 به شما امکان می‌دهد نشانی‌ها را به مختصات جغرافیایی تبدیل کنید و برعکس. موارد استفاده زیر به‌خوبی با سبک‌بندی داده‌محور برای مرزها ترکیب می‌شوند:

• از «زمین‌کدیابی» برای دریافت نمای هدف برای یک منطقه استفاده کنید.
• فیلتر کردن مؤلفه را در تماس «زمین‌کدیابی» خود اعمال کنید تا شناسه‌های مکان را برای تقسیمات کشوری ۱ تا ۴، محل، یا کد پستی دریافت کنید.
• از زمین‌کدیابی معکوس برای پیدا کردن شناسه‌های جا براساس مختصات عرض جغرافیایی/طول جغرافیایی استفاده کنید، یا حتی شناسه‌های جا را برای همه مؤلفه‌ها در یک مکان خاص برگردانید.

دریافت ناحیه نمایش برای یک منطقه

سرویس «زمین‌کدیابی» می‌تواند شناسه مکان را بگیرد و نمای دیدی برگرداند که می‌توانید آن را به تابع 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
```