SpeedScan API

API رسمی SpeedScan برای اجرای تست و دریافت نتایج

با یک کلید API می‌توانید تست سرعت را مستقیماً از کد خودتان اجرا کنید، نتیجه‌ی هر اجرای موتور تحلیل را به‌صورت JSON بگیرید و تاریخچه‌ی اسکن‌های حساب خود را بخوانید — همان قابلیتی که پنل استفاده می‌کند، بدون رابط گرافیکی.

REST · JSON API Key Auth v1 پایدار

فعال وضعیت API در حال حاضر پاسخ‌گوی درخواست‌های واقعی است.

v1 نسخه تغییرات ناسازگار همیشه در یک نسخه‌ی جدید (v2) اعلام می‌شود.

JSON فرمت پاسخ تمام پاسخ‌ها و خطاها با همین ساختار برمی‌گردند.

احراز هویت

کلید API

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

Authorization: Bearer <YOUR_API_KEY>
# یا
X-API-Key: <YOUR_API_KEY>

برای دریافت کلید API ابتدا وارد حساب شوید.

محدودیت‌ها

سهمیه بر اساس پلن

هر تماس با POST /scans/create/ یک اسکن واقعی مصرف می‌کند و از همان سهمیه‌ی ماهانه‌ی پنل کم می‌شود — پلن‌ها سهمیه‌ی جدا برای API ندارند.

Free

۱۰ اسکن در ماه

Pro

۲۰۰ اسکن در ماه

Team

۱۰۰۰ اسکن در ماه

وضعیت سهمیه‌ی فعلی‌تان همیشه از GET /me/ قابل خواندن است؛ وقتی سهمیه تمام شود POST /scans/create/ با کد ۴۲۹ (quota_exceeded) پاسخ می‌دهد.

Endpoints

مسیرهای API — پایه: `/api/v1/`

روی هر مسیر بزنید تا پارامترها، نمونه‌ی کد (چند زبان) و پاسخ آن باز شود.

POST /scans/create/ اجرای یک تست سرعت جدید و دریافت نتیجه

چون موتور تحلیل واقعاً اجرا می‌شود، این درخواست همزمان (synchronous) است و بسته به سنگینی سایت ۱۰ ثانیه تا حدود ۲ دقیقه طول می‌کشد — timeout کلاینت را سخاوتمندانه تنظیم کنید.

curl -X POST https://speedscan.ir/api/v1/scans/create/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "mobile",
    "network": "4g",
    "mobile_device": "pixel_8"
  }'

import requests

resp = requests.post(
    "https://speedscan.ir/api/v1/scans/create/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "url": "https://example.com",
        "device": "mobile",
        "network": "4g",
        "mobile_device": "pixel_8",
    },
    timeout=180,
)
print(resp.json())

<?php
$ch = curl_init("https://speedscan.ir/api/v1/scans/create/");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 180,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://example.com",
        "device" => "mobile",
        "network" => "4g",
        "mobile_device" => "pixel_8",
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

var client = HttpClient.newHttpClient();
var body = """
    {"url":"https://example.com","device":"mobile","network":"4g","mobile_device":"pixel_8"}
    """;
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://speedscan.ir/api/v1/scans/create/"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

#include <curl/curl.h>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    if (!curl) return 1;

    std::string body =
        R"({"url":"https://example.com","device":"mobile","network":"4g","mobile_device":"pixel_8"})";

    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, "Authorization: Bearer YOUR_API_KEY");
    headers = curl_slist_append(headers, "Content-Type: application/json");

    curl_easy_setopt(curl, CURLOPT_URL, "https://speedscan.ir/api/v1/scans/create/");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body.c_str());
    curl_easy_setopt(curl, CURLOPT_TIMEOUT, 180L);

    CURLcode res = curl_easy_perform(curl);

    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(180) };
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");

var payload = new {
    url = "https://example.com",
    device = "mobile",
    network = "4g",
    mobile_device = "pixel_8"
};

var response = await client.PostAsJsonAsync(
    "https://speedscan.ir/api/v1/scans/create/", payload);

Console.WriteLine(await response.Content.ReadAsStringAsync());

url الزامی آدرس کامل با http/https؛ IPهای داخلی/لوکال مجاز نیستند.

device اختیاری پیش‌فرض "mobile".

mobileپیش‌فرض desktop bothهر دو

mobile_device اختیاری فقط وقتی device شامل mobile باشد اثر دارد؛ حذف = امولیشن پیش‌فرض موتور تحلیل. همین لیست از GET /meta/ هم قابل دریافت است.

moto_g_powerMoto G Power iphone_seiPhone SE iphone_12iPhone 12 iphone_15_pro_maxiPhone 15 Pro Max iphone_16_pro_maxiPhone 16 Pro Max iphone_17_pro_maxiPhone 17 Pro Max iphone_18_pro_maxiPhone 18 Pro Max pixel_5Pixel 5 pixel_8Pixel 8 galaxy_s20Galaxy S20 galaxy_s24_ultraGalaxy S24 Ultra galaxy_s25_ultraGalaxy S25 Ultra galaxy_s26_ultraGalaxy S26 Ultra xiaomi_redmi_note_13Xiaomi Redmi Note 13

network اختیاری throttling شبکه؛ حذف = پیش‌فرض موتور تحلیل. همین لیست از GET /meta/ هم قابل دریافت است.

no_throttlingبدون Throttling (اتصال واقعی) 2g2G 3g_slow3G کند 3g_fast3G سریع 4g4G 4g_fast4G سریع / کابل 5g5G fiberفیبر adslADSL

پاسخ ۲۰۱

{
  "success": true,
  "domain": "example.com",
  "access_link": "288a5e32-b86c-4715-b8ad-d8cc3f8f59b4",
  "report_url": "https://speedscan.ir/speedtest/result/288a5e32-.../",
  "results": {
    "mobile": {
      "id": 4021,
      "domain": "example.com",
      "device": "mobile",
      "performance_score": 92,
      "seo_score": 96,
      "accessibility_score": 88,
      "best_practices_score": 90,
      "first_contentful_paint_ms": 812.4,
      "largest_contentful_paint_ms": 1540.2,
      "total_blocking_time_ms": 40.0,
      "cumulative_layout_shift": 0.01,
      "speed_index_ms": 1390.6,
      "created_at_iso": "2026-09-19T09:40:00+00:00"
    }
  },
  "device_errors": {},
  "scans_remaining": 9
}

GET /scans/ لیست صفحه‌بندی‌شده‌ی تست‌های قبلی همین حساب

curl "https://speedscan.ir/api/v1/scans/?page=1&page_size=20" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

resp = requests.get(
    "https://speedscan.ir/api/v1/scans/",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"page": 1, "page_size": 20},
)
print(resp.json())

<?php
$ch = curl_init("https://speedscan.ir/api/v1/scans/?page=1&page_size=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: YOUR_API_KEY"],
]);
echo curl_exec($ch);
curl_close($ch);

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://speedscan.ir/api/v1/scans/?page=1&page_size=20"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

#include <curl/curl.h>

int main() {
    CURL* curl = curl_easy_init();
    if (!curl) return 1;

    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, "X-API-Key: YOUR_API_KEY");

    curl_easy_setopt(curl, CURLOPT_URL,
        "https://speedscan.ir/api/v1/scans/?page=1&page_size=20");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

    CURLcode res = curl_easy_perform(curl);

    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var response = await client.GetAsync(
    "https://speedscan.ir/api/v1/scans/?page=1&page_size=20");

Console.WriteLine(await response.Content.ReadAsStringAsync());

domain اختیاری فیلتر بر اساس بخشی از نام دامنه.

device اختیاری "mobile" یا "desktop".

page / page_size اختیاری page_size حداکثر ۱۰۰، پیش‌فرض ۲۰.

پاسخ ۲۰۰

{
  "count": 34,
  "page": 1,
  "num_pages": 2,
  "has_next": true,
  "has_previous": false,
  "results": [ { "...": "همان شکل هر آیتم در results پایین" } ]
}

GET /scans/<access_link>/ جزئیات کامل یک تست مشخص با UUID آن

curl https://speedscan.ir/api/v1/scans/288a5e32-b86c-4715-b8ad-d8cc3f8f59b4/ \
  -H "X-API-Key: YOUR_API_KEY"

import requests

access_link = "288a5e32-b86c-4715-b8ad-d8cc3f8f59b4"
resp = requests.get(
    f"https://speedscan.ir/api/v1/scans/{access_link}/",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(resp.json())

<?php
$accessLink = "288a5e32-b86c-4715-b8ad-d8cc3f8f59b4";
$ch = curl_init("https://speedscan.ir/api/v1/scans/{$accessLink}/");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: YOUR_API_KEY"],
]);
echo curl_exec($ch);
curl_close($ch);

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://speedscan.ir/api/v1/scans/288a5e32-b86c-4715-b8ad-d8cc3f8f59b4/"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

#include <curl/curl.h>

int main() {
    CURL* curl = curl_easy_init();
    if (!curl) return 1;

    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, "X-API-Key: YOUR_API_KEY");

    curl_easy_setopt(curl, CURLOPT_URL,
        "https://speedscan.ir/api/v1/scans/288a5e32-b86c-4715-b8ad-d8cc3f8f59b4/");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

    CURLcode res = curl_easy_perform(curl);

    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var response = await client.GetAsync(
    "https://speedscan.ir/api/v1/scans/288a5e32-b86c-4715-b8ad-d8cc3f8f59b4/");

Console.WriteLine(await response.Content.ReadAsStringAsync());

فقط تستی که متعلق به همین حساب باشد قابل خواندن است؛ در غیر این صورت ۴۰۴ برمی‌گردد. access_link همان UUID صفحه‌ی نتیجه (/speedtest/result/<access_link>/) است.

پاسخ ۲۰۰

{
  "id": 4021,
  "domain": "example.com",
  "device": "mobile",
  "performance_score": 92,
  "seo_score": 96,
  "accessibility_score": 88,
  "best_practices_score": 90,
  "first_contentful_paint_ms": 812.4,
  "largest_contentful_paint_ms": 1540.2,
  "total_blocking_time_ms": 40.0,
  "cumulative_layout_shift": 0.01,
  "speed_index_ms": 1390.6,
  "created_at_iso": "2026-09-19T09:40:00+00:00"
}

GET /me/ پلن، سهمیه‌ی باقی‌مانده و تعداد کل تماس‌های API

curl https://speedscan.ir/api/v1/me/ \
  -H "X-API-Key: YOUR_API_KEY"

import requests

resp = requests.get(
    "https://speedscan.ir/api/v1/me/",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(resp.json())

<?php
$ch = curl_init("https://speedscan.ir/api/v1/me/");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: YOUR_API_KEY"],
]);
echo curl_exec($ch);
curl_close($ch);

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://speedscan.ir/api/v1/me/"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

#include <curl/curl.h>

int main() {
    CURL* curl = curl_easy_init();
    if (!curl) return 1;

    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, "X-API-Key: YOUR_API_KEY");

    curl_easy_setopt(curl, CURLOPT_URL, "https://speedscan.ir/api/v1/me/");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

    CURLcode res = curl_easy_perform(curl);

    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var response = await client.GetAsync("https://speedscan.ir/api/v1/me/");
Console.WriteLine(await response.Content.ReadAsStringAsync());

پاسخ ۲۰۰

{
  "email": "you@example.com",
  "plan": "free",
  "scan_limit": 10,
  "scans_used_this_month": 3,
  "scans_remaining": 7,
  "total_scan_count": 41,
  "api_call_count": 128
}

GET /meta/ کلیدهای معتبر mobile_device و network — بدون نیاز به کلید API

curl https://speedscan.ir/api/v1/meta/

import requests

resp = requests.get("https://speedscan.ir/api/v1/meta/")
print(resp.json())

<?php
echo file_get_contents("https://speedscan.ir/api/v1/meta/");

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://speedscan.ir/api/v1/meta/"))
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

#include <curl/curl.h>

int main() {
    CURL* curl = curl_easy_init();
    if (!curl) return 1;

    curl_easy_setopt(curl, CURLOPT_URL, "https://speedscan.ir/api/v1/meta/");
    CURLcode res = curl_easy_perform(curl);

    curl_easy_cleanup(curl);
    return 0;
}

using var client = new HttpClient();
var response = await client.GetAsync("https://speedscan.ir/api/v1/meta/");
Console.WriteLine(await response.Content.ReadAsStringAsync());

پاسخ ۲۰۰

{
  "mobile_device_profiles": {
    "pixel_8": "Pixel 8",
    "iphone_15_pro_max": "iPhone 15 Pro Max"
  },
  "network_profiles": {
    "4g": "4G",
    "3g_slow": "3G کند"
  }
}

خطاها

کدهای خطا

401

missing_api_key / invalid_api_key

هدر کلید API خالی یا نامعتبر است.

403

api_access_disabled

دسترسی API از پروفایل غیرفعال شده است.

400

invalid_url / invalid_device / invalid_json / ...

ورودی درخواست نامعتبر است؛ متن message دلیل دقیق را می‌گوید.

429

quota_exceeded

سهمیه‌ی ماهانه‌ی پلن تمام شده است.

502

scan_failed

اجرای موتور تحلیل شکست خورد (سایت در دسترس نبود، SSL نامعتبر و ...)؛ device_errors جزئیات هر device را دارد.

API رسمی SpeedScan برای اجرای تست و دریافت نتایج

کلید API

سهمیه بر اساس پلن

مسیرهای API — پایه: /api/v1/

پاسخ ۲۰۱

پاسخ ۲۰۰

پاسخ ۲۰۰

پاسخ ۲۰۰

پاسخ ۲۰۰

کدهای خطا

مسیرهای API — پایه: `/api/v1/`