# تبدیل آدرس به نقطه


<span id="overview"></span>

با این سرویس می‌توانید یک آدرس متنی را به نقطه‌ای روی نقشه تبدیل کنید؛ مثلاً آدرس واردشده در فرم سفارش را به مختصات قابل ذخیره تبدیل کنید.

برای ارسال درخواست از سرور، یک [کلید خصوصی](/dashboard/docs/authentication) با دسترسی این سرویس بسازید.

<span id="use-cases"></span>

## موارد استفاده

- تبدیل آدرس واردشده توسط کاربر به مختصات قابل ذخیره.
- پیشنهاد چند گزینه برای آدرس‌های مبهم.
- اولویت‌بندی نتایج با توجه به موقعیت کاربر یا محدوده نقشه.

برای تفاوت موقعیت کاربر و مرکز نقشه، [نمودار زمینهٔ مکانی جستجو](/dashboard/docs/search#موقعیت-کاربر-و-نمای-نقشه) را ببینید.

<span id="address-to-point"></span>

## دریافت مختصات از آدرس

`GET https://search.services.balad.ir/v5/geocoding/`

آدرس یا نام مکان را به گزینه‌های مکانی تبدیل می‌کند. پارامترهای مکانی برای رفع ابهام‌اند؛ مثلاً «خیابان آزادی» در چند شهر وجود دارد و مرکز منطقهٔ موردنظر به انتخاب نتیجه کمک می‌کند. این پارامترها فیلتر قطعی محدوده نیستند. اگر نام شهر از متن تشخیص داده شود، همان شهر بر موقعیت ارسالی اولویت دارد.

### تبدیل آدرس به مختصات


#### cURL

```bash
curl --get "https://search.services.balad.ir/v5/geocoding/" \
  --data-urlencode "text=تهران میدان آزادی" \
  -H "Authorization: Bearer <BALAD_API_KEY>"
```


#### Python

```python
# Install: pip install httpx
import httpx

url = "https://search.services.balad.ir/v5/geocoding/"
params = {
    "text": "تهران میدان آزادی",
}
response = httpx.get(
    url,
    params=params,
    headers={"Authorization": "Bearer <BALAD_API_KEY>"},
    timeout=10.0,
)
response.raise_for_status()
print(response.text)
```


#### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
)

func main() {
	endpoint, err := url.Parse("https://search.services.balad.ir/v5/geocoding/")
	if err != nil {
		panic(err)
	}
	query := endpoint.Query()
	query.Set("text", "تهران میدان آزادی")
	endpoint.RawQuery = query.Encode()
	request, err := http.NewRequest("GET", endpoint.String(), nil)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer <BALAD_API_KEY>")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	if response.StatusCode < 200 || response.StatusCode >= 300 {
		panic(fmt.Sprintf("HTTP %d", response.StatusCode))
	}
	if _, err := io.Copy(os.Stdout, response.Body); err != nil {
		panic(err)
	}
}
```


#### PowerShell

```powershell
$url = "https://search.services.balad.ir/v5/geocoding/"
$params = @{
    text = "تهران میدان آزادی"
}
$query = ($params.GetEnumerator() | ForEach-Object {
    [uri]::EscapeDataString([string]$_.Key) + "=" + [uri]::EscapeDataString([string]$_.Value)
}) -join "&"
$url += "?" + $query
$headers = @{ Authorization = "Bearer <BALAD_API_KEY>" }
Invoke-RestMethod -Uri $url -Headers $headers
```


#### PHP

```php
<?php
// Install: composer require guzzlehttp/guzzle
require __DIR__ . "/vendor/autoload.php";

$client = new \GuzzleHttp\Client();
$response = $client->get("https://search.services.balad.ir/v5/geocoding/", [
    "headers" => ["Authorization" => "Bearer <BALAD_API_KEY>"],
    "query" => [
        "text" => "تهران میدان آزادی",
    ],
    "timeout" => 10,
]);
echo $response->getBody();
```


#### Node.js

```javascript
// Node.js 18+
async function main() {
  const url = new URL("https://search.services.balad.ir/v5/geocoding/");
  const params = {
    text: "تهران میدان آزادی",
  };
  url.search = new URLSearchParams(params).toString();
  const response = await fetch(url, {
    headers: { Authorization: "Bearer <BALAD_API_KEY>" },
  });
  if (!response.ok) throw new Error("HTTP " + response.status);
  console.log(await response.text());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```




### رفع ابهام آدرس با مرکز منطقهٔ موردنظر


#### cURL

```bash
curl --get "https://search.services.balad.ir/v5/geocoding/" \
  --data-urlencode "text=خیابان آزادی" \
  --data-urlencode "camera=51.3890,35.6892" \
  -H "Authorization: Bearer <BALAD_API_KEY>"
```


#### Python

```python
# Install: pip install httpx
import httpx

url = "https://search.services.balad.ir/v5/geocoding/"
params = {
    "text": "خیابان آزادی",
    "camera": "51.3890,35.6892",
}
response = httpx.get(
    url,
    params=params,
    headers={"Authorization": "Bearer <BALAD_API_KEY>"},
    timeout=10.0,
)
response.raise_for_status()
print(response.text)
```


#### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
)

func main() {
	endpoint, err := url.Parse("https://search.services.balad.ir/v5/geocoding/")
	if err != nil {
		panic(err)
	}
	query := endpoint.Query()
	query.Set("text", "خیابان آزادی")
	query.Set("camera", "51.3890,35.6892")
	endpoint.RawQuery = query.Encode()
	request, err := http.NewRequest("GET", endpoint.String(), nil)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer <BALAD_API_KEY>")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	if response.StatusCode < 200 || response.StatusCode >= 300 {
		panic(fmt.Sprintf("HTTP %d", response.StatusCode))
	}
	if _, err := io.Copy(os.Stdout, response.Body); err != nil {
		panic(err)
	}
}
```


#### PowerShell

```powershell
$url = "https://search.services.balad.ir/v5/geocoding/"
$params = @{
    text = "خیابان آزادی"
    camera = "51.3890,35.6892"
}
$query = ($params.GetEnumerator() | ForEach-Object {
    [uri]::EscapeDataString([string]$_.Key) + "=" + [uri]::EscapeDataString([string]$_.Value)
}) -join "&"
$url += "?" + $query
$headers = @{ Authorization = "Bearer <BALAD_API_KEY>" }
Invoke-RestMethod -Uri $url -Headers $headers
```


#### PHP

```php
<?php
// Install: composer require guzzlehttp/guzzle
require __DIR__ . "/vendor/autoload.php";

$client = new \GuzzleHttp\Client();
$response = $client->get("https://search.services.balad.ir/v5/geocoding/", [
    "headers" => ["Authorization" => "Bearer <BALAD_API_KEY>"],
    "query" => [
        "text" => "خیابان آزادی",
        "camera" => "51.3890,35.6892",
    ],
    "timeout" => 10,
]);
echo $response->getBody();
```


#### Node.js

```javascript
// Node.js 18+
async function main() {
  const url = new URL("https://search.services.balad.ir/v5/geocoding/");
  const params = {
    text: "خیابان آزادی",
    camera: "51.3890,35.6892",
  };
  url.search = new URLSearchParams(params).toString();
  const response = await fetch(url, {
    headers: { Authorization: "Bearer <BALAD_API_KEY>" },
  });
  if (!response.ok) throw new Error("HTTP " + response.status);
  console.log(await response.text());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```




### ارسال موقعیت کاربر و نمای فعلی نقشه


#### cURL

```bash
curl --get "https://search.services.balad.ir/v5/geocoding/" \
  --data-urlencode "text=خیابان آزادی" \
  --data-urlencode "location=51.3890,35.6892" \
  --data-urlencode "camera=51.40,35.725" \
  --data-urlencode "sw=51.30,35.65" \
  --data-urlencode "ne=51.50,35.80" \
  --data-urlencode "zoom=14.5" \
  -H "Authorization: Bearer <BALAD_API_KEY>"
```


#### Python

```python
# Install: pip install httpx
import httpx

url = "https://search.services.balad.ir/v5/geocoding/"
params = {
    "text": "خیابان آزادی",
    "location": "51.3890,35.6892",
    "camera": "51.40,35.725",
    "sw": "51.30,35.65",
    "ne": "51.50,35.80",
    "zoom": "14.5",
}
response = httpx.get(
    url,
    params=params,
    headers={"Authorization": "Bearer <BALAD_API_KEY>"},
    timeout=10.0,
)
response.raise_for_status()
print(response.text)
```


#### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
)

func main() {
	endpoint, err := url.Parse("https://search.services.balad.ir/v5/geocoding/")
	if err != nil {
		panic(err)
	}
	query := endpoint.Query()
	query.Set("text", "خیابان آزادی")
	query.Set("location", "51.3890,35.6892")
	query.Set("camera", "51.40,35.725")
	query.Set("sw", "51.30,35.65")
	query.Set("ne", "51.50,35.80")
	query.Set("zoom", "14.5")
	endpoint.RawQuery = query.Encode()
	request, err := http.NewRequest("GET", endpoint.String(), nil)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer <BALAD_API_KEY>")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	if response.StatusCode < 200 || response.StatusCode >= 300 {
		panic(fmt.Sprintf("HTTP %d", response.StatusCode))
	}
	if _, err := io.Copy(os.Stdout, response.Body); err != nil {
		panic(err)
	}
}
```


#### PowerShell

```powershell
$url = "https://search.services.balad.ir/v5/geocoding/"
$params = @{
    text = "خیابان آزادی"
    location = "51.3890,35.6892"
    camera = "51.40,35.725"
    sw = "51.30,35.65"
    ne = "51.50,35.80"
    zoom = "14.5"
}
$query = ($params.GetEnumerator() | ForEach-Object {
    [uri]::EscapeDataString([string]$_.Key) + "=" + [uri]::EscapeDataString([string]$_.Value)
}) -join "&"
$url += "?" + $query
$headers = @{ Authorization = "Bearer <BALAD_API_KEY>" }
Invoke-RestMethod -Uri $url -Headers $headers
```


#### PHP

```php
<?php
// Install: composer require guzzlehttp/guzzle
require __DIR__ . "/vendor/autoload.php";

$client = new \GuzzleHttp\Client();
$response = $client->get("https://search.services.balad.ir/v5/geocoding/", [
    "headers" => ["Authorization" => "Bearer <BALAD_API_KEY>"],
    "query" => [
        "text" => "خیابان آزادی",
        "location" => "51.3890,35.6892",
        "camera" => "51.40,35.725",
        "sw" => "51.30,35.65",
        "ne" => "51.50,35.80",
        "zoom" => "14.5",
    ],
    "timeout" => 10,
]);
echo $response->getBody();
```


#### Node.js

```javascript
// Node.js 18+
async function main() {
  const url = new URL("https://search.services.balad.ir/v5/geocoding/");
  const params = {
    text: "خیابان آزادی",
    location: "51.3890,35.6892",
    camera: "51.40,35.725",
    sw: "51.30,35.65",
    ne: "51.50,35.80",
    zoom: "14.5",
  };
  url.search = new URLSearchParams(params).toString();
  const response = await fetch(url, {
    headers: { Authorization: "Bearer <BALAD_API_KEY>" },
  });
  if (!response.ok) throw new Error("HTTP " + response.status);
  console.log(await response.text());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```




### نمونه پاسخ

```json
{
  "results": [
    {
      "id": "poi:azadi-square",
      "type": "poi",
      "maintext": "میدان آزادی",
      "subtext1": "تهران",
      "center_point": { "lat": 35.6997, "lng": 51.3379 }
    }
  ]
}
```

### پارامترها

| نام | نوع | اجباری | پیش‌فرض | توضیح |
| --- | --- | --- | --- | --- |
| `text` | `string` | بله | ندارد | متن آدرس یا مکان. |
| `location` | `string` | خیر | ندارد | موقعیت جغرافیایی کاربر، مثلاً از GPS، به ترتیب طول و عرض جغرافیایی: `51.3890,35.6892`. این نقطه آدرس مقصد نیست و ممکن است با منطقهٔ موردنظر فرق داشته باشد. برای تعیین منطقهٔ جستجو به‌تنهایی به آن تکیه نکنید و `camera` را هم بفرستید. |
| `camera` | `string` | خیر | ندارد | مرکز نمای فعلی نقشه به ترتیب `longitude,latitude`؛ مانند `51.3890,35.6892`. اگر نقشه ندارید، مرکز شهر یا منطقهٔ موردنظر را بفرستید؛ برای جستجوی اطراف کاربر، آن را برابر موقعیت کاربر بگذارید. |
| `sw` | `string` | خیر | ندارد | گوشهٔ جنوب‌غربی کادر دیده‌شدهٔ نقشه به ترتیب `longitude,latitude`؛ مانند `51.30,35.65`. همراه `ne` بفرستید تا سرویس موقعیت کاربر را نسبت به نمای نقشه بسنجد؛ نتایج الزاماً داخل این کادر نیستند. |
| `ne` | `string` | خیر | ندارد | گوشهٔ شمال‌شرقی همان کادر به ترتیب `longitude,latitude`؛ مانند `51.50,35.80`. همراه `sw` بفرستید؛ طول و عرض این گوشه باید از طول و عرض گوشهٔ `sw` بیشتر باشند. |
| `zoom` | `number` | خیر | ندارد | بزرگ‌نمایی فعلی نقشه؛ عدد بزرگ‌تر یعنی نمای نزدیک‌تر، مانند `14.5`. همراه موقعیت کاربر و کادر نقشه در انتخاب موقعیت مرجع نقش دارد. در منطق انتخاب مرکز، مقدار `7` و بالاتر امکان استفاده از `camera` به‌جای موقعیت کاربر را فراهم می‌کند؛ این عدد شعاع جستجو نیست. |

### فیلدهای پاسخ

| نام | نوع | توضیح |
| --- | --- | --- |
| `results` | `array<object>` | گزینه‌های پیشنهادی برای آدرس. |
| `results[].maintext` | `string` | عنوان اصلی نتیجه. |
| `results[].subtext1` | `string` | متن مکمل یا آدرس کوتاه. |
| `results[].center_point` | `object` | مختصات نقطه پیشنهادی. |
| `results[].geometry` | `object` | هندسه مرتبط با نتیجه، در صورت وجود. |
| `results[].type` | `string` | نوع مکان: `poi` مکان مشخص مثل فروشگاه یا بیمارستان؛ `other-poi` مکان مشخصی که توکن POI در پاسخ آن موجود نیست؛ `road` معبر مثل خیابان یا کوچه؛ `road_intersection` تقاطع معابر؛ `roundabout` میدان؛ `neighborhood` محله؛ `city` شهر؛ `county` شهرستان؛ `province` استان؛ `village` روستا. |
| `results[].id` | `string` | شناسه نتیجه. |

### کدهای وضعیت

کدهای مستند این درخواست: `200`، `204`، `400`، `401`، `403`، `404`، `429`، `5xx`. [معنی کدها و راه بررسی خطا](/dashboard/docs/status-codes)

### نکات

- برای فرم آدرس بدون نقشه، اگر نام شهر را می‌دانید آن را در `text` بیاورید؛ مانند «تهران، خیابان آزادی». در غیر این صورت، `camera` را به مرکز منطقهٔ موردنظر تنظیم کنید. نیازی به ساختن `sw`، `ne` و `zoom` فرضی نیست.
- با جابه‌جایی نقشه، `camera`، `sw`، `ne` و `zoom` را از نمای جدید بگیرید؛ `location` همچنان موقعیت خود کاربر است. نبود زمینهٔ مکانی به معنی جستجوی بی‌طرف در سراسر کشور نیست؛ اگر شهر از متن تشخیص داده نشود و مرکز معتبری انتخاب نشود، سرویس از نقطهٔ پیش‌فرضی در تهران استفاده می‌کند.