اولین درخواست API

در این راهنما مختصات یک نقطه را می‌فرستید و آدرس آن را دریافت می‌کنید. درخواست را در ترمینال یا روی سرور برنامه اجرا کنید.

پیش‌نیازها

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

ساخت کلید خصوصی

1. در داشبورد، سازمان خود را انتخاب یا ایجاد کنید.
2. یک کلید خصوصی با دسترسی «تبدیل نقطه به آدرس» بسازید.
3. محدودیت IP کلید را مطابق سروری که درخواست را می‌فرستد تنظیم کنید.

کلید خصوصی را در کد مرورگر یا مخزن عمومی قرار ندهید.

ارسال درخواست

مقدار <BALAD_API_KEY> را با کلید خصوصی جایگزین کنید:

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;
});

پارامتر location به ترتیب longitude,latitude است؛ در این نمونه، 51.3890 طول جغرافیایی و 35.6892 عرض جغرافیایی است.

خواندن پاسخ

پاسخ، آدرس خوانا را در formatted_address و اجزای آدرس را در components برمی‌گرداند. ساختار نمونه:

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

نام و جزئیات آدرس به نقطهٔ ورودی بستگی دارد. از formatted_address برای نمایش به کاربر و از components برای خواندن اجزای آدرس استفاده کنید.

بررسی خطا

• 401: کلید ارسال نشده است؛ هدر Authorization را بررسی کنید.
• 403: فعال‌بودن کلید و سازمان، سرویس‌های مجاز و محدودیت IP را بررسی کنید.
• 400: فرمت و مقدار مختصات را بررسی کنید.

مصرف درخواست موفق پس از پاسخ 2xx ثبت می‌شود. مرجع تبدیل نقطه به آدرس پارامترها و فیلدهای پاسخ را توضیح می‌دهد.

انتخاب آدرس در تسویه‌حساب · کدهای وضعیت