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

انتخاب پلاتفرم: 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 برای دریافت شناسه مکان Trinidad، کالیفرنیا، ایجاد کنیم و سپس سبک را به محدوده اعمال کنیم:

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