اولین نقشهٔ شما از اینجا آغاز می‌شود.

۱. فضای کاری خود را ایجاد کنید

Sign in with Firebase Google، بخش کلیدهای API را باز کرده برای برنامه خود کلید بسازید. فوراً کاپی کنید؛ فقط یک بار نمایش داده می‌شود.

۲. هویت درخواست‌ها را تأیید کنید

استفاده کنید ازx-api-keyدر سربرگ درخواست. نمونه‌ها از localhost استفاده می‌کنند؛ آن را با نشانی پلتفرم نشرشده جایگزین کنید.

curl "http://localhost:3000/api/v1/places/search?q=Kabul"   -H "x-api-key: YOUR_API_KEY"

کلید سرور را در متغیر محیطی نگه دارید. کلید مرورگر یا نقشه جاسازی‌شده عمومی است؛ کلیدی جدا با حد روزانه بسازید.

جستجوی مکان‌ها

const response = await fetch(
  "/api/v1/places/search?q=Kabul&lang=en",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const { data } = await response.json();

q: نام مکان یا کسب‌وکار. lang: en، fa یا ps.category: شناسهٔ دسته. فقط مکان‌ها و کسب‌وکارهای تأییدشده در نتایج عمومی نمایش داده می‌شوند.

دریافت دسته‌ها ازGET /api/v1/categoriesو معلومات مکان ازGET /api/v1/places/:id.

یافتن مسیر

GET /api/v1/route?fromLat=34.5553&fromLng=69.2075
    &toLat=34.3529&toLng=62.2040&mode=driving

حالت‌ها: موتر، پیاده و بایسکل. مختصات درجهٔ اعشاری WGS84 است. پاسخ شامل فاصله به متر، زمان به ثانیه، مراحل و مسیر GeoJSON است. مسیریابی نیازمند خدمت OSRM با دادهٔ آماده است.

نمایش کاشی‌های نقشه

/api/v1/tiles/{z}/{x}/{y}.png?lang=fa&key=YOUR_API_KEY

در کتابخانه نقشه از کاشی تصویری ۲۵۶ پیکسلی استفاده کنید. زبان‌ها: انگلیسی، دری و پشتو. اعتبار مشارکت‌کنندگان OpenStreetMap را نمایش دهید.

جاسازی در هر صفحه HTML

<iframe
 src="http://localhost:3000/embed?lat=34.5553&lng=69.2075&zoom=15&lang=fa&theme=light&3d=1&userId=STABLE_USER_ID&key=YOUR_API_KEY"
 title="Rayab map" width="100%" height="450"
 style="border:0;border-radius:16px"
 loading="lazy" referrerpolicy="no-referrer">
</iframe>

استفاده کنید ازسازندهٔ کد جاسازیبرای تنظیم کد. هر درخواست کاشی، یک درخواست از سهمیهٔ فضای کاری مصرف می‌کند.

نقشه روز، شب و سه‌بعدی

Embed options: theme=light or theme=dark; 3d=1 enables buildings; lang=en, fa or ps chooses map labels. Each map style, tile and font request uses the same package allowance.

GET /api/v1/basemap/style?lang=fa&dark=1&3d=1
Headers: x-api-key: YOUR_API_KEY
         x-masir-user-id: STABLE_USER_ID

When an end-user limit is configured, provide the same stable ID for that user through x-masir-user-id or userId. The backend stores only a hash. New user IDs stop being accepted when the monthly limit is reached.

On 401, 402, 403 or 429, hide your map and show the returned message. The Rayab embed does this automatically and rechecks access every 10 seconds. Never replace rejected assets with unmetered public map URLs. A 429 response includes Retry-After in seconds.

مصرف، محدودیت‌ها و پرداخت‌ها

The Free package includes 10,000 requests in each 10-minute window, shared across all workspace keys. Your portal shows live usage and the configured package limits. Admins can configure monthly allowances, active key limits and monthly end-user limits for each package. Requests accepted by the metering guard count once, including downstream failures.

After a monthly allowance is used, API requests consume purchased top-up credits. Renewals and request top-ups are available in your portal and activate only after verified payment confirmation. Without credits, the API returns402. پرداخت خودکار وجود ندارد. هر کلید حد روزانهٔ قابل تنظیم نیز دارد.

حساب‌ها و کسب‌وکارهای موبایل

برنامه موبایل Rayab با گوگل یا اپل از طریق Firebase وارد می‌شود. توکن Firebase را بفرستید به POST /api/mobile/auth/firebase as { "idToken": "..." }. سرور توکن را تأیید و عضو را با Firebase UID ایجاد یا همگام می‌کند. توکن‌های دسترسی و تازه‌سازی را در حافظه امن دستگاه ذخیره کنید. توکن دسترسی را بفرستید به شکلAuthorization: Bearer TOKEN.

تازه‌سازی باPOST /api/mobile/auth/firebaseby obtaining a fresh Firebase ID token and sending it تا POST /api/mobile/auth/firebase. Password-based mobile login and registration are disabled. Submit a business using POST /api/mobile/businesses؛ categoryId، name، latitude و longitude ضروری است. ثبت‌ها تا بررسی پلتفرم در انتظار می‌مانند.

بخش‌های دیگر: دستگاه‌ها، ذخیره‌ها، نظرها، گزارش‌ها و اشتراک موقعیت موقت در/api/mobile. برنامه‌های موبایل دیگر باید از نسخهٔ دارای شمارش مصرف استفاده کنند:/api/v1برای خدمات نقشه با کلید خودشان.