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


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

## پیش‌نیازها

- حساب و سازمان فعال در [داشبورد بلد](/dashboard/organizations).
- یک کلید خصوصی با دسترسی «تبدیل نقطه به آدرس» و ابزار یا محیط اجرای یکی از نمونه‌های زیر.

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

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

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

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

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


#### cURL

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


#### Python

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

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

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

```javascript
// 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` برمی‌گرداند. ساختار نمونه:

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

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

## بررسی خطا

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

مصرف درخواست موفق پس از پاسخ `2xx` ثبت می‌شود. [مرجع تبدیل نقطه به آدرس](/dashboard/docs/reverse-geocoding#point-to-address) پارامترها و فیلدهای پاسخ را توضیح می‌دهد.

[انتخاب آدرس در تسویه‌حساب](/dashboard/docs/guides/checkout-address-picker) · [کدهای وضعیت](/dashboard/docs/status-codes)