نمایش نقشهٔ تصویری

نقشهٔ تصویری از کنار هم قرار گرفتن تصویرهای کوچکی به نام تایل ساخته می‌شود. این نقشه برای نمایش در سایت و ساخت تصویر ثابت مناسب است. اگر می‌خواهید رنگ‌ها، نوشته‌ها یا لایه‌های نقشه را تغییر دهید، نقشهٔ برداری انتخاب مناسب‌تری است.

با این نقشه چه کارهایی می‌توان کرد؟

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

نقشه را به صفحه اضافه کنید

برای نمایش نقشه از MapLibre GL JS، کتابخانه‌ای برای نمایش نقشه در مرورگر، استفاده می‌کنیم. یک کلید عمومی با دسترسی نقشهٔ تصویری بسازید و مبدأ سایت خود را در تنظیمات کلید ثبت کنید.

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

قطعه کد

<link href="https://cdn.balad.ir/balad-static-files/platform/maplibre/5.24.0/maplibre-gl.css" rel="stylesheet">
<div id="map" style="height: 400px"></div>
<script src="https://cdn.balad.ir/balad-static-files/platform/maplibre/5.24.0/maplibre-gl.js"></script>
<script>
const map = new maplibregl.Map({
  container: "map",
  style: "https://tile-raster.services.balad.ir/styles/raster.json?api_key=YOUR_PUBLIC_API_KEY",
  center: [51.389, 35.6892],
  zoom: 12,
  minZoom: 3,
  attributionControl: { compact: false },
});
</script>

HTML کامل

<!doctype html>
<html lang="fa" dir="rtl">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>نقشه تصویری بلد</title>
<link href="https://cdn.balad.ir/balad-static-files/platform/maplibre/5.24.0/maplibre-gl.css" rel="stylesheet">
<style>html, body, #map { margin: 0; width: 100%; height: 100%; }</style>
<div id="map"></div>
<script src="https://cdn.balad.ir/balad-static-files/platform/maplibre/5.24.0/maplibre-gl.js"></script>
<script>
const map = new maplibregl.Map({
  container: "map",
  style: "https://tile-raster.services.balad.ir/styles/raster.json?api_key=YOUR_PUBLIC_API_KEY",
  center: [51.389, 35.6892],
  zoom: 12,
  minZoom: 3,
  attributionControl: { compact: false },
});
</script>
</html>

پس از بارگذاری صفحه، نقشه‌ای می‌بینید که می‌توانید آن را جابه‌جا و بزرگ‌نمایی کنید.

مرکز، بزرگ‌نمایی و نشانگر

در کد بالا، center نقطهٔ شروع نقشه به ترتیب طول جغرافیایی، عرض جغرافیایی است. zoom میزان نزدیکی نما را مشخص می‌کند؛ مثلاً تغییر آن از 12 به 15 خیابان‌ها را از نزدیک‌تر نشان می‌دهد.

center: [51.389, 35.6892],
zoom: 15,

برای نمایش مکان موردنظر، این کد را پس از ساخت map و داخل همان تگ script قرار دهید:

new maplibregl.Marker()
  .setLngLat([51.389, 35.6892])
  .addTo(map);

برای افزودن نام یا آدرس به نشانگر، نمونهٔ پنجرهٔ اطلاعات را ببینید.

نمایش منبع نقشه

طبق قوانین بلد، نام و کپی‌رایت بلد و OpenStreetMap باید روی نقشه قابل مشاهده بماند. حذف آن ممکن است به بسته‌شدن حساب شما منجر شود. نمونه‌های این صفحه اطلاعات منبع را روی نقشه نمایش می‌دهند؛ آن‌ها را حذف یا پنهان نکنید.

اگر نقشه دیده نمی‌شود، کلید عمومی، دسترسی نقشهٔ تصویری، مبدأ مجاز و ارتفاع بخش نقشه را بررسی کنید.

تصویر ثابت نقشه

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

دریافت تصویر ثابت با مرکز

GET https://tile-raster.services.balad.ir/tiles/image/{z},{lon},{lat}/{width}x{height}[@{scale}x].jpg

یک تصویر ثابت از نقشه با مرکز، سطح بزرگ‌نمایی و اندازه مشخص برمی‌گرداند. برای پیش‌نمایش سفارش، رسید یا اشتراک‌گذاری موقعیت مناسب است.

تصویر ثابت با نشانگر

cURL

curl --get "https://tile-raster.services.balad.ir/tiles/image/15,51.3890,35.6892/640x360@2x.jpg" \
  --data-urlencode "pin=1" \
  -H "Authorization: Bearer <BALAD_API_KEY>" \
  --fail --output map.jpg

Python

# Install: pip install httpx
from pathlib import Path

import httpx

url = "https://tile-raster.services.balad.ir/tiles/image/15,51.3890,35.6892/640x360@2x.jpg"
params = {
    "pin": "1",
}
response = httpx.get(
    url,
    params=params,
    headers={"Authorization": "Bearer <BALAD_API_KEY>"},
    timeout=10.0,
)
response.raise_for_status()
Path("map.jpg").write_bytes(response.content)

Go

package main

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

func main() {
  endpoint, err := url.Parse("https://tile-raster.services.balad.ir/tiles/image/15,51.3890,35.6892/640x360@2x.jpg")
  if err != nil {
    panic(err)
  }
  query := endpoint.Query()
  query.Set("pin", "1")
  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))
  }
  file, err := os.Create("map.jpg")
  if err != nil {
    panic(err)
  }
  defer file.Close()
  if _, err := io.Copy(file, response.Body); err != nil {
    panic(err)
  }
}

PowerShell

$url = "https://tile-raster.services.balad.ir/tiles/image/15,51.3890,35.6892/640x360@2x.jpg"
$params = @{
    pin = "1"
}
$query = ($params.GetEnumerator() | ForEach-Object {
    [uri]::EscapeDataString([string]$_.Key) + "=" + [uri]::EscapeDataString([string]$_.Value)
}) -join "&"
$url += "?" + $query
$headers = @{ Authorization = "Bearer <BALAD_API_KEY>" }
Invoke-WebRequest -Uri $url -Headers $headers -UseBasicParsing -OutFile "map.jpg"

PHP

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

$client = new \GuzzleHttp\Client();
$response = $client->get("https://tile-raster.services.balad.ir/tiles/image/15,51.3890,35.6892/640x360@2x.jpg", [
    "headers" => ["Authorization" => "Bearer <BALAD_API_KEY>"],
    "query" => [
        "pin" => "1",
    ],
    "timeout" => 10,
]);
if (file_put_contents("map.jpg", $response->getBody()->getContents()) === false) {
    throw new RuntimeException("Could not save image");
}

Node.js

// Node.js 18+
async function main() {
  const url = new URL("https://tile-raster.services.balad.ir/tiles/image/15,51.3890,35.6892/640x360@2x.jpg");
  const params = {
    pin: "1",
  };
  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);
  const { writeFile } = await import("node:fs/promises");
  await writeFile("map.jpg", Buffer.from(await response.arrayBuffer()));
}

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

در این نمونه pin=1 نشانگر را در مرکز قرار می‌دهد. اندازهٔ درخواستی 640x360 است و با @2x، فایل خروجی ۱۲۸۰ در ۷۲۰ پیکسل خواهد بود.

تأثیر بزرگ‌نمایی

هر دو تصویر زیر مرکز یکسانی دارند. در z=13 محدودهٔ بیشتری دیده می‌شود و در z=16 نمای خیابان‌ها نزدیک‌تر است.

پاسخ

HTTP/1.1 200 OK
Content-Type: image/jpeg

<binary jpeg image>

پارامترها

نام	نوع	اجباری	پیش‌فرض	توضیح
z	path integer	بله	ندارد	سطح بزرگ‌نمایی تصویر.
lon	path number	بله	ندارد	طول جغرافیایی مرکز تصویر.
lat	path number	بله	ندارد	عرض جغرافیایی مرکز تصویر.
width	path integer	بله	ندارد	عرض تصویر خروجی بر حسب پیکسل.
height	path integer	بله	ندارد	ارتفاع تصویر خروجی بر حسب پیکسل.
scale	path integer	خیر	1	ضریب کیفیت تصویر؛ مثل @2x.
pin	query boolean	خیر	ندارد	در صورت مقدار 1، نشانگر مرکز روی تصویر اضافه می‌شود.

فیلدهای پاسخ

نام	نوع	توضیح
body	image/jpeg	تصویر ثابت نقشه
Cache-Control	header	هدر کش پاسخ.

کدهای وضعیت

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

دریافت تصویر ثابت از محدوده

GET https://tile-raster.services.balad.ir/tiles/image/bbox/{minLon},{minLat},{maxLon},{maxLat}/{width}x{height}[@{scale}x].jpg

تصویر ثابت نقشه را طوری تولید می‌کند که محدوده جغرافیایی مشخص‌شده داخل تصویر قرار بگیرد.

تصویر ثابت از محدوده

cURL

curl --get "https://tile-raster.services.balad.ir/tiles/image/bbox/51.30,35.65,51.45,35.75/800x500.jpg" \
  -H "Authorization: Bearer <BALAD_API_KEY>" \
  --fail --output bbox.jpg

Python

# Install: pip install httpx
from pathlib import Path

import httpx

url = "https://tile-raster.services.balad.ir/tiles/image/bbox/51.30,35.65,51.45,35.75/800x500.jpg"
response = httpx.get(
    url,
    headers={"Authorization": "Bearer <BALAD_API_KEY>"},
    timeout=10.0,
)
response.raise_for_status()
Path("bbox.jpg").write_bytes(response.content)

Go

package main

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

func main() {
  request, err := http.NewRequest("GET", "https://tile-raster.services.balad.ir/tiles/image/bbox/51.30,35.65,51.45,35.75/800x500.jpg", 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))
  }
  file, err := os.Create("bbox.jpg")
  if err != nil {
    panic(err)
  }
  defer file.Close()
  if _, err := io.Copy(file, response.Body); err != nil {
    panic(err)
  }
}

PowerShell

$url = "https://tile-raster.services.balad.ir/tiles/image/bbox/51.30,35.65,51.45,35.75/800x500.jpg"
$headers = @{ Authorization = "Bearer <BALAD_API_KEY>" }
Invoke-WebRequest -Uri $url -Headers $headers -UseBasicParsing -OutFile "bbox.jpg"

PHP

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

$client = new \GuzzleHttp\Client();
$response = $client->get("https://tile-raster.services.balad.ir/tiles/image/bbox/51.30,35.65,51.45,35.75/800x500.jpg", [
    "headers" => ["Authorization" => "Bearer <BALAD_API_KEY>"],
    "timeout" => 10,
]);
if (file_put_contents("bbox.jpg", $response->getBody()->getContents()) === false) {
    throw new RuntimeException("Could not save image");
}

Node.js

// Node.js 18+
async function main() {
  const url = new URL("https://tile-raster.services.balad.ir/tiles/image/bbox/51.30,35.65,51.45,35.75/800x500.jpg");
  const response = await fetch(url, {
    headers: { Authorization: "Bearer <BALAD_API_KEY>" },
  });
  if (!response.ok) throw new Error("HTTP " + response.status);
  const { writeFile } = await import("node:fs/promises");
  await writeFile("bbox.jpg", Buffer.from(await response.arrayBuffer()));
}

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

چهار عدد محدوده به ترتیب minLon,minLat,maxLon,maxLat هستند. کادر بنفش برای توضیح ترتیب گوشه‌ها شماتیک است؛ تصویر خروجی ممکن است اطراف محدوده را هم نشان دهد.

پاسخ

HTTP/1.1 200 OK
Content-Type: image/jpeg

<binary jpeg image>

پارامترها

نام	نوع	اجباری	پیش‌فرض	توضیح
minLon	path number	بله	ندارد	کمینه طول جغرافیایی محدوده.
minLat	path number	بله	ندارد	کمینه عرض جغرافیایی محدوده.
maxLon	path number	بله	ندارد	بیشینه طول جغرافیایی محدوده.
maxLat	path number	بله	ندارد	بیشینه عرض جغرافیایی محدوده.
width	path integer	بله	ندارد	عرض تصویر خروجی بر حسب پیکسل.
height	path integer	بله	ندارد	ارتفاع تصویر خروجی بر حسب پیکسل.
scale	path integer	خیر	1	ضریب کیفیت تصویر؛ مثل @2x.

فیلدهای پاسخ

نام	نوع	توضیح
body	image/jpeg	تصویر ثابت محدوده
Cache-Control	header	هدر کش پاسخ.

کدهای وضعیت

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