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

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

برای ارسال درخواست از سرور، یک کلید خصوصی با دسترسی این سرویس بسازید.

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

• نمایش آدرس فارسی کاربر بعد از انتخاب نقطه روی نقشه.
• استخراج شهر، محله، خیابان یا تقاطع نزدیک به یک مختصات.
• کمک به تکمیل فرم آدرس با نقطه‌ای که کاربر انتخاب کرده است.

برای نمایش یک نشانی، دریافت آدرس کامل را ببینید. برای یافتن مکان از یک نوع مشخص، مانند محله، از یافتن نزدیک‌ترین مکان استفاده کنید.

دریافت آدرس کامل

GET https://reverse-geocoding.services.balad.ir/v1/

با دریافت مختصات در قالب longitude,latitude، آدرس قالب‌بندی‌شده و اجزای ساخت‌یافته آدرس را برمی‌گرداند.

نمونه درخواست

cURL

curl --get "https://reverse-geocoding.services.balad.ir/v1/" \
  --data-urlencode "location=51.3890,35.6892" \
  -H "Authorization: Bearer <BALAD_API_KEY>"

Python

# Install: pip install httpx
import httpx

url = "https://reverse-geocoding.services.balad.ir/v1/"
params = {
    "location": "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

package main

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

func main() {
  endpoint, err := url.Parse("https://reverse-geocoding.services.balad.ir/v1/")
  if err != nil {
    panic(err)
  }
  query := endpoint.Query()
  query.Set("location", "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

$url = "https://reverse-geocoding.services.balad.ir/v1/"
$params = @{
    location = "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
// Install: composer require guzzlehttp/guzzle
require __DIR__ . "/vendor/autoload.php";

$client = new \GuzzleHttp\Client();
$response = $client->get("https://reverse-geocoding.services.balad.ir/v1/", [
    "headers" => ["Authorization" => "Bearer <BALAD_API_KEY>"],
    "query" => [
        "location" => "51.3890,35.6892",
    ],
    "timeout" => 10,
]);
echo $response->getBody();

Node.js

// Node.js 18+
async function main() {
  const url = new URL("https://reverse-geocoding.services.balad.ir/v1/");
  const params = {
    location: "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;
});

نمونه پاسخ

{
  "formatted_address": "تهران، خیابان انقلاب اسلامی، حوالی میدان فردوسی",
  "components": [
    { "name": "تهران", "type": "city" },
    { "name": "انقلاب اسلامی", "type": "road" }
  ]
}

پارامترها

نام	نوع	اجباری	پیش‌فرض	توضیح
location	string	بله	ندارد	مختصات نقطه در قالب longitude,latitude؛ مانند 51.3890,35.6892.

فیلدهای پاسخ

نام	نوع	توضیح
formatted_address	string	آدرس خوانا و قالب‌بندی‌شده برای نمایش به کاربر.
components	array<object>	اجزای آدرس مثل شهر، محله، خیابان و پلاک، در صورت وجود.
components[].name	string	نام جزء آدرس.
components[].type	string	نوع جزء آدرس؛ برای نمونه، city، neighborhood یا road.

کدهای وضعیت

کدهای مستند این درخواست: 200، 204، 400، 401، 403، 404، 429، 5xx. معنی کدها و راه بررسی خطا

یافتن نزدیک‌ترین مکان

GET https://reverse-geocoding.services.balad.ir/v1/features

با گرفتن مختصات و نوع مکان، نزدیک‌ترین مکان از آن نوع را برمی‌گرداند؛ مانند شهر، محله، خیابان یا تقاطع.

دریافت محله نزدیک

cURL

curl --get "https://reverse-geocoding.services.balad.ir/v1/features" \
  --data-urlencode "location=51.3890,35.6892" \
  --data-urlencode "result_type=neighborhood" \
  -H "Authorization: Bearer <BALAD_API_KEY>"

Python

# Install: pip install httpx
import httpx

url = "https://reverse-geocoding.services.balad.ir/v1/features"
params = {
    "location": "51.3890,35.6892",
    "result_type": "neighborhood",
}
response = httpx.get(
    url,
    params=params,
    headers={"Authorization": "Bearer <BALAD_API_KEY>"},
    timeout=10.0,
)
response.raise_for_status()
print(response.text)

Go

package main

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

func main() {
  endpoint, err := url.Parse("https://reverse-geocoding.services.balad.ir/v1/features")
  if err != nil {
    panic(err)
  }
  query := endpoint.Query()
  query.Set("location", "51.3890,35.6892")
  query.Set("result_type", "neighborhood")
  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

$url = "https://reverse-geocoding.services.balad.ir/v1/features"
$params = @{
    location = "51.3890,35.6892"
    result_type = "neighborhood"
}
$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
// Install: composer require guzzlehttp/guzzle
require __DIR__ . "/vendor/autoload.php";

$client = new \GuzzleHttp\Client();
$response = $client->get("https://reverse-geocoding.services.balad.ir/v1/features", [
    "headers" => ["Authorization" => "Bearer <BALAD_API_KEY>"],
    "query" => [
        "location" => "51.3890,35.6892",
        "result_type" => "neighborhood",
    ],
    "timeout" => 10,
]);
echo $response->getBody();

Node.js

// Node.js 18+
async function main() {
  const url = new URL("https://reverse-geocoding.services.balad.ir/v1/features");
  const params = {
    location: "51.3890,35.6892",
    result_type: "neighborhood",
  };
  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;
});

نمونه پاسخ

{
  "name": "فردوسی",
  "type": "neighborhood",
  "geometry": {
    "type": "Polygon",
    "coordinates": []
  }
}

پارامترها

نام	نوع	اجباری	پیش‌فرض	توضیح
location	string	بله	ندارد	مختصات نقطه در قالب longitude,latitude.
result_type	enum	بله	ندارد	نوع مکانی که می‌خواهید پیدا کنید. مقدارهای رایج: city، county، neighborhood، road، road_intersection و roundabout.

فیلدهای پاسخ

نام	نوع	توضیح
name	string	نام مکان یافت‌شده.
type	string	نوع مکان یافت‌شده.
geometry	object	شکل هندسی مکان در قالب GeoJSON یا ساختار معادل سرویس.

کدهای وضعیت

کدهای مستند این درخواست: 200، 204، 400، 401، 403، 404، 429، 5xx. معنی کدها و راه بررسی خطا