نشانی‌یابی و نشانی از مختصات

تبدیل نشانی به مختصات (آزاد یا ساختاریافته) با درجه اطمینان، و تبدیل مختصات به نشانی فارسی خوانا.

در این صفحه

نشانی‌یابی
پارامترهای نشانی‌یابی
اطمینان و سطح تطبیق
نشانی از مختصات
پارامترهای نشانی از مختصات
پاسخ نشانی

نشانی‌یابی

GET /v1/geocode نشانی را به مختصات تبدیل می‌کند؛ یا نشانی آزاد در address یا فیلدهای جدا (خیابان، پلاک، شهر، کد پستی…). دسترسی maps:search، سرویس maps.geocode، یک واحد برای هر پاسخ موفق.

نشانی‌یابی

curl -sS "https://maps.namayek.com/v1/geocode?address=%D8%AA%D9%87%D8%B1%D8%A7%D9%86%D8%8C%20%D9%88%D9%84%DB%8C%D8%B9%D8%B5%D8%B1%D8%8C%20%D9%BE%D9%84%D8%A7%DA%A9%2012" \  -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"

curl -sS "https://maps.namayek.com/v1/geocode?street=%D9%88%D9%84%DB%8C%D8%B9%D8%B5%D8%B1&houseNumber=12&city=%D8%AA%D9%87%D8%B1%D8%A7%D9%86&country=ir" \  -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"

// نشانی آزادconst free = await NamayekMaps.geocode("تهران، خیابان ولیعصر، پلاک ۱۲", { key: "nmk_pk_YOUR_PUBLISHABLE_KEY" }); // نشانی ساختاریافتهconst structured = await NamayekMaps.geocode(  { street: "ولیعصر", houseNumber: "12", city: "تهران", country: "ir" },  { key: "nmk_pk_YOUR_PUBLISHABLE_KEY", limit: 3 },);console.log(structured.items[0].confidence, structured.items[0].matchLevel);

پارامترهای نشانی‌یابی

پارامترهای /v1/geocode
پارامتر	نوع	لزوم	پیش‌فرض	توضیح
`address`	`string`	یا یکی از فیلدهای ساختاریافته	—	نشانی آزاد تا ۳۰۰ نویسه؛ با فیلدهای ساختاریافته با هم نمی‌آید.
`street`	`string`	اختیاری	—	خیابان تا ۱۲۰ نویسه (می‌تواند پلاک را هم داشته باشد).
`houseNumber`	`string`	اختیاری	—	پلاک تا ۲۰ نویسه؛ رقم فارسی هم پذیرفته و به لاتین تبدیل می‌شود.
`city / county / state`	`string`	اختیاری	—	شهر، شهرستان، استان؛ هر کدام تا ۸۰ نویسه.
`postcode`	`string`	اختیاری	—	کد پستی ۵ تا ۱۰ رقمی (کد پستی ایران ۱۰ رقم).
`country`	`alpha-2`	اختیاری	کشور اول پروژه یا ir	کد دوحرفی کشور.
`limit`	`integer`	اختیاری	5	از ۱ تا ۱۰.
`lang`	`fa \| en \| fa-en`	اختیاری	زبان پیش‌فرض پروژه	زبان متن نتیجه‌ها.
`key`	`string`	یا سرآیند	—	فقط کلید عمومی nmk_pk_ در نشانی؛ روی سرور کلید را در سرآیند X-Namayek-Key بفرستید.

دست‌کم یکی از address، street، city، county، state یا postcode لازم است (وگرنه MISSING_PARAM).

اطمینان و سطح تطبیق

هر نتیجه افزون بر فیلدهای نتیجه جست‌وجو این‌ها را دارد و نتیجه‌ها به ترتیب نزولی اطمینان مرتب‌اند:

فیلدهای ویژه نشانی‌یابی
فیلد	نوع / مقدار	توضیح
`confidence`	`number`	اطمینان از ۰ تا ۱ با دو رقم اعشار؛ نتیجه‌ها به ترتیب نزولی همین عدد.
`matchLevel`	`house \| street \| neighbourhood \| city \| county \| state \| postcode \| country`	دقیق‌ترین سطحی که با نشانی شما جور شد.
`components`	`AddressComponents`	بخش‌های نشانی (همان فیلدهای پاسخ نشانی از مختصات).

GET /v1/reverse برای یک نقطه نشانی فارسی خوانا می‌سازد. سرویس maps.reverse، یک واحد برای هر پاسخ موفق (حتی وقتی نشانی پیدا نشود). نقطه بیرون از محدوده داده OUT_OF_COVERAGE می‌گیرد و هزینه ندارد.

نشانی از مختصات

curl -sS "https://maps.namayek.com/v1/reverse?lat=35.757&lng=51.41&zoom=18&detail=street&digits=fa" \  -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"

map.on("click", async (e) => {  const r = await map.reverse(e.lngLat, { detail: "street" });  console.log(r.address?.formatted ?? "نشانی پیدا نشد");});

پارامترهای نشانی از مختصات

پارامترهای /v1/reverse
پارامتر	نوع	لزوم	پیش‌فرض	توضیح
`lat`	`number`	لازم	—	عرض جغرافیایی.
`lng`	`number`	لازم	—	طول جغرافیایی.
`zoom`	`integer 3..18`	اختیاری	18	سطح جزئیات: ۱۸ ساختمان، ۱۶ خیابان، ۱۴ محله، ۱۰ شهر، ۵ استان.
`detail`	`basic \| street`	اختیاری	basic	street خط خیابان دقیق‌تر می‌سازد (فقط با zoom ۱۶ یا بیشتر).
`lang`	`fa \| en`	اختیاری	زبان پیش‌فرض پروژه	زبان نشانی.
`digits`	`fa \| latin`	اختیاری	fa برای فارسی	رقم‌های formatted، line و long؛ components همیشه رقم لاتین دارد.
`key`	`string`	یا سرآیند	—	فقط کلید عمومی nmk_pk_ در نشانی؛ روی سرور کلید را در سرآیند X-Namayek-Key بفرستید.

پاسخ نشانی

پاسخ ۲۰۰

{  "available": true,  "location": [51.41, 35.757],  "address": {    "formatted": "تهران، ونک، خیابان ولیعصر، پلاک ۱۲",    "line": "خیابان ولیعصر، پلاک ۱۲",    "long": "ایران، استان تهران، تهران، ونک، خیابان ولیعصر، پلاک ۱۲",    "components": {      "country": "ایران", "countryCode": "ir", "state": "استان تهران", "county": "شهرستان تهران",      "city": "تهران", "district": "منطقه 3", "neighbourhood": "ونک", "street": "ولیعصر",      "streetLabel": "خیابان ولیعصر", "houseNumber": "12", "postcode": null, "place": null    }  },  "place": null,  "distance": 8.4,  "attribution": "© مشارکت کنندگان OpenStreetMap"}

فیلدهای پاسخ نشانی
فیلد	نوع / مقدار	توضیح
`location`	`[lng, lat]`	نقطه درخواست با ۶ رقم اعشار.
`address.formatted`	`string`	نشانی کوتاه و خوانا («تهران، ونک، خیابان ولیعصر، پلاک ۱۲»).
`address.line`	`string \| null`	خط خیابان و پلاک.
`address.long`	`string`	نشانی کامل از کشور تا پلاک.
`address.components`	`AddressComponents`	country، countryCode، state، county، city، district، neighbourhood، street، streetLabel، houseNumber، postcode، place.
`place`	`object \| null`	مکان نام‌دار همان نقطه (id، title، kind، category).
`distance`	`number \| null`	فاصله به متر تا شیء پیدا شده.
`attribution`	`string`	متن انتساب داده.

نقطه بی داده (دریا، بیابان) پاسخ ۲۰۰ با address: null و place: null دارد.
detail=street خط خیابان دقیق‌تر را با چند جست‌وجوی اضافه در محدوده زمانی کوتاه می‌سازد؛ هزینه همان یک واحد است.

آخرین به‌روزرسانی: ۱ آبان ۱۴۰۵

نشانی‌یابی و نشانی از مختصات