هدهد ویژن

مستندات API هدهد ویژن

راهنمای ساده و کامل API خبر و API رایگان قیمت ارز، طلا و خودرو: شروع سریع در ۵ دقیقه، توضیح کلید و آدرس مجاز، نمونه کد Python، PHP، Node و وردپرس و رفع خطاها.

شروع سریع؛ اولین خبر در ۵ دقیقه

اگر تازه با API کار می‌کنید نگران نباشید: API یعنی یک آدرس اینترنتی که به‌جای صفحه‌ی وب، داده می‌دهد. شما از سرور خودتان به آن آدرس درخواست می‌فرستید و خبرها را به شکل JSON (متن ساختاریافته) تحویل می‌گیرید.

  1. کلید بگیرید: در صفحه‌ی «API خبر» پلن «تست رایگان» را انتخاب کنید، مراحل را کامل کنید و کلیدی شبیه hk_live_… بگیرید. کلید فقط یک بار نمایش داده می‌شود؛ همان لحظه ذخیره‌اش کنید.
  2. آدرس مجاز را درست وارد کنید: هنگام خرید باید بگویید فراخوانی از کجا انجام می‌شود: دامنه‌ی سایتتان (example.ir) یا IP سرورتان. کلید فقط از همین آدرس کار می‌کند.
  3. از سرور خودتان این دستور را بزنید: کلید را جایگزین YOUR_KEY کنید و دستور زیر را روی سرور (نه روی مرورگر) اجرا کنید.
  4. پاسخ را ببینید: اگر همه‌چیز درست باشد کدِ ۲۰۰ و فهرست خبرها را می‌گیرید. اگر خطا گرفتید به بخش «خطاها و راه‌حل» بروید؛ هر خطا یک راه‌حل روشن دارد.

curl

curl -H "X-API-Key: YOUR_KEY" "https://hodhodvision.ir/api/v1/feed/?limit=5"

نکته: نمی‌دانید IP سرورتان چیست؟ دستور https://hodhodvision.ir/api/v1/feed/info/ را با همان کلید بزنید؛ در پاسخ فیلد your_ip همان IPای است که ما از شما می‌بینیم.

مفاهیم؛ چند کلمه‌ی ساده

واژهیعنی چه؟
کلید API (key)رمز اختصاصی شما شبیه hk_live_… ؛ مثل کارت ورود. فقط در سرور خودتان نگهش دارید.
آدرس مجازتنها دامنه یا IPای که کلید از آن کار می‌کند. آدرس دوم هرگز پذیرفته نمی‌شود.
چارچوب (فیلتر)انتخاب‌های شما هنگام خرید: حوزه، استان، شهر، کلیدواژه. فقط خبرهای داخل این چارچوب برگردانده می‌شود.
seqشماره‌ی ترتیب انتشار هر خبر. خبر تازه‌تر seq بزرگ‌تری دارد.
cursorseq آخرین خبری که گرفته‌اید. دفعه‌ی بعد آن را در since بدهید تا فقط خبرهای جدید برسد.
attributionنام و پیوند منبع. هنگام نمایش خبر باید «هدهد ویژن» را با همین پیوند بنویسید.

کلید و آدرس مجاز

کلید را در هدر X-API-Key بفرستید (یا Authorization: Bearer YOUR_KEY). کلید را هرگز در نشانی (query string) نگذارید و در جاوااسکریپت صفحه نگذارید.

آدرس مجاز چطور بررسی می‌شود؟

اگر ثبت کرده‌ایدقاعدهمثال
یک IPفراخوانی باید دقیقاً از همان IP باشد.185.10.20.30
یک دامنهIP سرور فراخواننده باید یکی از IPهایی باشد که DNS دامنه (و www آن) به آن اشاره می‌کند؛ حداکثر ۴ IP.example.ir

هشدار: سایتتان پشت CDN (مثل کلودفلر) است؟ DNS دامنه به IP کلودفلر اشاره می‌کند، نه سرور شما. در این حالت هنگام خرید «IP» سرور خودتان را ثبت کنید، نه دامنه.

چرا فراخوانی از مرورگر ممنوع است؟

هر کدی که در مرورگر کاربر اجرا شود، کلید شما را برای همه قابل دیدن می‌کند. به همین دلیل درخواستی که هدر Origin مرورگر داشته باشد با خطای browser_not_allowed رد می‌شود. راه درست: سرور شما خبر را بگیرد و در صفحه‌ی خودتان نشان دهد.

چه چیزی باعث مسدود شدن کلید می‌شود؟

  • ۵۰ تلاش از آدرس غیرمجاز در ۲۴ ساعت، کلید را خودکار مسدود می‌کند (پشتیبانی بازش می‌کند).
  • بیش از ۲۰ کلید اشتباه از یک IP در ده دقیقه، آن IP را موقتاً می‌بندد.
  • اگر کلیدتان لو رفت، از پنل «کلید جدید» بسازید؛ کلید قبلی همان لحظه باطل می‌شود.

دریافت خبر: GET /api/v1/feed/

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

پارامترنوعمعنی
sinceعدد (اختیاری)فقط خبرهای بعد از این seq؛ از قدیم به جدید مرتب. ندهید → جدیدترین خبرها از جدید به قدیم.
limitعدد ۱ تا ۵۰تعداد خبر در هر پاسخ. پیش‌فرض ۲۰.

دو حالت استفاده

  • بدون since — «آخرین خبرها»: مناسب نمایش ۱۰ خبر اخیر در صفحه‌ی اصلی سایت.
  • با since — «همگام‌سازی»: مناسب ذخیره‌ی همه‌ی خبرهای جدید در پایگاه‌داده‌ی خودتان بدون هیچ خبر جاافتاده یا تکراری.

نمونه‌ی پاسخ

{
  "count": 2,
  "cursor": 48214,
  "has_more": false,
  "results": [
    {
      "id": 5121,
      "seq": 48213,
      "title": "عنوان خبر",
      "url": "https://hodhodvision.ir/news-5121",
      "category": "economy",
      "category_label": "اقتصاد",
      "excerpt": "خلاصه‌ی خبر…",
      "body": "متن کامل خبر…",
      "image": "https://hodhodvision.ir/media/news/5121.jpg",
      "published_at": "2026-11-17T09:12:00+03:30",
      "province": "yazd",
      "province_label": "یزد",
      "is_local": true,
      "topic": "",
      "is_breaking": false,
      "keywords": ["بورس", "یزد"],
      "attribution": { "name": "هدهد ویژن", "url": "https://hodhodvision.ir/", "required": true }
    }
  ],
  "subscription": { "expires_at": "2026-12-17T09:00:00+03:30", "plan": "month" }
}

فیلدهای هر خبر

فیلدمعنی
id / seqشناسه خبر و شماره ترتیب انتشار؛ seq را به‌عنوان cursor نگه دارید
title / excerpt / bodyعنوان، خلاصه و متن کامل (متن کامل را می‌توان خاموش کرد)
urlنشانی صفحه خبر در هدهد ویژن؛ نمایش پیوند الزامی است
category / category_labelدسته‌ی خبر مثل economy و برچسب فارسی آن
province / province_label / is_localاستان و محلی‌بودن خبر
topic / is_breaking / is_featuredموضوع ویژه، خبر فوری و خبر ویژه
imageنشانی مطلق تصویر خبر
published_atزمان انتشار ISO 8601 با منطقه‌ی زمانی تهران
keywordsکلیدواژه‌های خبر
attributionنام و پیوند منبع که باید نمایش داده شود

فیلدهای بالای پاسخ

فیلدمعنی
countتعداد خبر در همین پاسخ
cursorseq آخرین خبر؛ دفعه‌ی بعد به‌عنوان since بفرستید
has_moretrue یعنی خبر جدیدتری هم هست؛ بلافاصله دوباره بپرسید. false یعنی فعلاً تمام است؛ یک دقیقه صبر کنید
subscriptionتاریخ انقضا و پلن شما

یک خبر و وضعیت کلید

آدرسکاربرد
GET /api/v1/feed/{id}/یک خبر مشخص با شناسه‌ی id. اگر خارج از چارچوب اشتراک شما باشد ۴۰۴ می‌دهد.
GET /api/v1/feed/info/وضعیت کلید: پلن، انقضا، آدرس ثبت‌شده، IP که ما از شما می‌بینیم (your_ip) و فیلترها. برای تست اتصال عالی است.

curl

curl -H "X-API-Key: YOUR_KEY" "https://hodhodvision.ir/api/v1/feed/info/"

الگوی درست همگام‌سازی خبر

اگر می‌خواهید همه‌ی خبرهای تازه را در پایگاه‌داده‌ی خودتان داشته باشید، این چرخه را اجرا کنید:

  1. cursor را بخوانید: بار اول 0 است. بعد از هر دور آن را در فایل یا پایگاه‌داده ذخیره کنید تا با ری‌استارت برنامه از نو شروع نشود.
  2. درخواست بزنید: GET /feed/?since=CURSOR&limit=50
  3. خبرها را ذخیره کنید و cursor را به‌روز کنید: cursor پاسخ را ذخیره کنید.
  4. اگر has_more درست بود دوباره بپرسید، وگرنه ۶۰ ثانیه صبر کنید: بیشتر از دقیقه‌ای یک‌بار پرسیدن لازم نیست و سقف ۱۲۰ درخواست در دقیقه را هم هدر می‌دهد.

Python

import os, time, json, pathlib, requests

KEY = os.environ["HODHOD_API_KEY"]            # کلید را در متغیر محیطی نگه دارید، نه در کد
URL = "https://hodhodvision.ir/api/v1/feed/"
STATE = pathlib.Path("hodhod_cursor.json")     # آخرین cursor اینجا ذخیره می‌شود

cursor = json.loads(STATE.read_text())["cursor"] if STATE.exists() else 0

while True:
    r = requests.get(URL, headers={"X-API-Key": KEY}, params={"since": cursor, "limit": 50}, timeout=15)
    if r.status_code == 429:                   # سقف درخواست؛ کمی صبر کنید
        time.sleep(int(r.headers.get("Retry-After", 30)))
        continue
    r.raise_for_status()
    data = r.json()
    for n in data["results"]:
        print(n["title"], n["url"])            # اینجا خبر را در پایگاه‌داده یا سایت خودتان ذخیره کنید
    cursor = data["cursor"]
    STATE.write_text(json.dumps({"cursor": cursor}))
    if not data["has_more"]:
        time.sleep(60)                         # خبر تازه‌ای نیست؛ یک دقیقه بعد دوباره بپرسید

Node.js

// Node 18+ ؛ فقط روی سرور اجرا شود
import { readFile, writeFile } from "node:fs/promises";

const KEY = process.env.HODHOD_API_KEY;
const URL_ = "https://hodhodvision.ir/api/v1/feed/";
let cursor = 0;
try { cursor = JSON.parse(await readFile("cursor.json", "utf8")).cursor; } catch {}

while (true) {
  const res = await fetch(`${URL_}?since=${cursor}&limit=50`, { headers: { "X-API-Key": KEY } });
  if (res.status === 429) { await new Promise(r => setTimeout(r, 30000)); continue; }
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const data = await res.json();
  for (const n of data.results) console.log(n.title, n.url);   // ذخیره در پایگاه‌داده
  cursor = data.cursor;
  await writeFile("cursor.json", JSON.stringify({ cursor }));
  if (!data.has_more) await new Promise(r => setTimeout(r, 60000));
}

دستورالعمل‌های آماده

نمایش ۱۰ خبر اخیر در سایت PHP (با کش ۵ دقیقه‌ای)

PHP

<?php
// news.php — خبرها را از هدهد می‌گیرد، ۵ دقیقه کش می‌کند و نمایش می‌دهد.
$cacheFile = __DIR__ . "/hodhod_cache.json";
if (!file_exists($cacheFile) || time() - filemtime($cacheFile) > 300) {
    $ch = curl_init("https://hodhodvision.ir/api/v1/feed/?limit=10");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("HODHOD_API_KEY")],
    ]);
    $body = curl_exec($ch);
    if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200) file_put_contents($cacheFile, $body);
}
$news = json_decode(@file_get_contents($cacheFile), true)["results"] ?? [];
?>
<ul>
<?php foreach ($news as $n): ?>
  <li><a href="<?= htmlspecialchars($n["url"]) ?>"><?= htmlspecialchars($n["title"]) ?></a>
      <small>منبع: <a href="<?= htmlspecialchars($n["attribution"]["url"]) ?>">هدهد ویژن</a></small></li>
<?php endforeach; ?>
</ul>

وردپرس

WordPress

<?php
// functions.php قالب — خبر هدهد را با کش ۵ دقیقه‌ای برمی‌گرداند
function hodhod_news($limit = 10) {
    $cached = get_transient('hodhod_news');
    if ($cached !== false) return $cached;
    $r = wp_remote_get('https://hodhodvision.ir/api/v1/feed/?limit=' . intval($limit), [
        'headers' => ['X-API-Key' => HODHOD_API_KEY],   // در wp-config.php تعریف کنید
        'timeout' => 15,
    ]);
    if (is_wp_error($r) || wp_remote_retrieve_response_code($r) !== 200) return [];
    $news = json_decode(wp_remote_retrieve_body($r), true)['results'] ?? [];
    set_transient('hodhod_news', $news, 300);
    return $news;
}
// در قالب: foreach (hodhod_news() as $n) { echo '<a href="'.esc_url($n['url']).'">'.esc_html($n['title']).'</a>'; }

ارسال خودکار خبر به کانال تلگرام

Python

import os, time, requests

KEY, BOT, CHAT = os.environ["HODHOD_API_KEY"], os.environ["BOT_TOKEN"], os.environ["CHAT_ID"]
cursor = 0
while True:
    r = requests.get("https://hodhodvision.ir/api/v1/feed/", headers={"X-API-Key": KEY}, params={"since": cursor, "limit": 10}, timeout=15)
    r.raise_for_status()
    data = r.json()
    for n in data["results"]:
        text = f"{n['title']}\n{n['url']}\nمنبع: هدهد ویژن"
        requests.post(f"https://api.telegram.org/bot{BOT}/sendMessage", json={"chat_id": CHAT, "text": text}, timeout=15)
    cursor = data["cursor"]
    time.sleep(0 if data["has_more"] else 60)

نکته: در همه‌ی نمونه‌ها کنار هر خبر «منبع: هدهد ویژن» را با پیوند فیلد url بنویسید؛ این شرط استفاده است.

خطاها و راه‌حل

هر خطا یک JSON مثل نمونه‌ی زیر است؛ فیلد code را بخوانید، نه فقط کد HTTP.

{
  "error": {
    "code": "ip_mismatch",
    "message": "این کلید فقط برای example.ir فعال است و از این آدرس (203.0.113.9) پذیرفته نمی‌شود.",
    "your_ip": "203.0.113.9",
    "bound_to": "example.ir",
    "bound_type": "domain"
  }
}
HTTPcodeیعنی چه؟چه کنم؟
401missing_keyکلید فرستاده نشدههدر X-API-Key را اضافه کنید.
401invalid_keyکلید اشتباه یا باطل‌شدهکلید را از پنل بررسی کنید؛ اگر کلید جدید ساخته‌اید قبلی باطل است.
403ip_mismatchIP فراخوان با IP ثبت‌شده فرق دارددر پاسخ your_ip را ببینید؛ از همان سرور صدا بزنید یا با پشتیبانی آدرس را عوض کنید.
403ip_not_in_dnsIP فراخوان جزو IPهای DNS دامنه نیستاز سروری صدا بزنید که دامنه به آن اشاره می‌کند، یا به‌جای دامنه IP ثبت کنید.
403dns_unresolvedدامنه‌ی ثبت‌شده DNS نداردرکورد A دامنه را بررسی کنید.
403dns_too_many_ipsدامنه بیش از ۴ IP داردحالت IP را استفاده کنید.
403browser_not_allowedدرخواست از مرورگر آمدهفراخوانی را به سرور خودتان ببرید.
403subscription_expiredاشتراک تمام شدهاز صفحه‌ی API خبر تمدید کنید؛ کلید عوض نمی‌شود.
403suspendedکلید مسدود شدهبا پشتیبانی تماس بگیرید.
404not_foundاین خبر در چارچوب شما نیستشناسه یا فیلترها را بررسی کنید.
429rate_limitedبیش از ۱۲۰ درخواست در دقیقههدر Retry-After را صبر کنید و تعداد درخواست را کم کنید.
429blockedتلاش‌های اشتباه زیاد از این IPده دقیقه صبر کنید.

مدیریت اشتراک: تمدید، فیلتر، کلید جدید

  • ورود: در صفحه‌ی API خبر با نام کاربری و رمزتان وارد شوید؛ بخش «اشتراک‌های من» باز می‌شود.
  • تمدید: دکمه‌ی «تمدید» → پلن را انتخاب کنید. مدت جدید به انتهای اشتراک فعلی اضافه می‌شود و کلید عوض نمی‌شود.
  • ویرایش فیلتر: رایگان و بی‌درنگ اعمال می‌شود. فقط آدرس مجاز قابل تغییر نیست.
  • کلید جدید: اگر کلید لو رفت بسازید. کلید قبلی همان لحظه باطل می‌شود؛ روزی حداکثر ۳ بار.

API رایگان قیمت ارز، طلا، سکه و خودرو

این API کلید و ثبت‌نام نمی‌خواهد و از مرورگر هم قابل فراخوانی است (CORS آزاد). تنها شرط: نام «هدهد ویژن» را با پیوند کنار قیمت‌ها نشان دهید. حداکثر ۱۲۰ درخواست در دقیقه برای هر IP؛ نتیجه را حداقل یک دقیقه کش کنید.

  1. درخواست بزنید: برای دلار: GET https://hodhodvision.ir/api/v1/open/prices/?keys=usd
  2. مقدار را بخوانید: در results[0].value قیمت و در unit واحد (تومان یا دلار) است.
  3. منبع را بنویسید: کنار قیمت بنویسید: «منبع: هدهد ویژن» با پیوند به hodhodvision.ir.

curl

curl "https://hodhodvision.ir/api/v1/open/prices/?keys=usd,gold18"

JavaScript

const r = await fetch("https://hodhodvision.ir/api/v1/open/prices/?keys=usd");
const { results } = await r.json();
document.querySelector("#usd").textContent =
  results[0].value.toLocaleString("fa-IR") + " " + results[0].unit;

Python

import requests
r = requests.get("https://hodhodvision.ir/api/v1/open/prices/", params={"keys": "usd,eur"}, timeout=15)
for p in r.json()["results"]:
    print(p["label"], p["value"], p["unit"])

PHP

<?php
$d = json_decode(file_get_contents("https://hodhodvision.ir/api/v1/open/prices/?keys=usd"), true);
echo number_format($d["results"][0]["value"]);

قیمت ارز، طلا و سکه: /open/prices/

پارامترمعنی
keysاختیاری؛ کلیدها با ویرگول، مثل usd,gold18. ندهید → همه.
keyچیست؟واحد
usdدلار آمریکاتومان
eurیوروتومان
gbpپوند انگلیستومان
aedدرهم اماراتتومان
usdtتترتومان
gold18طلای ۱۸ عیار (هر گرم)تومان
coinسکه امامیتومان
nimنیم‌سکهتومان
onsاونس جهانی طلادلار
brentنفت برنتدلار
btcبیت‌کویندلار
ethاتریومدلار
{
  "count": 1,
  "updated_at": "2026-11-17T09:30:00+00:00",
  "results": [
    {
      "key": "usd",
      "label": "دلار آمریکا",
      "value": 268375.0,
      "unit": "تومان",
      "change": -330.0,
      "change_pct": -0.12,
      "updated_at": "2026-11-17T09:30:00+00:00",
      "stale": false
    }
  ],
  "attribution": { "name": "هدهد ویژن", "url": "https://hodhodvision.ir/", "required": true }
}

تک‌قلم: GET /api/v1/open/prices/usd/ . فیلد stale اگر true باشد یعنی قیمت چند دقیقه است به‌روز نشده؛ updated_at زمان آخرین به‌روزرسانی است.

قیمت روز خودرو: /open/cars/

پارامترمعنی
brandکلید برند، مثل saipa یا irankhodro (فهرست در /open/cars/brands/)
modelکلید مدل
yearسال ساخت (مثلاً 1404)
qجست‌وجوی متنی در برند، مدل و تیپ
min_price / max_priceبازه‌ی قیمت به تومان
limit / offsetصفحه‌بندی؛ limit حداکثر ۲۰۰

curl

curl "https://hodhodvision.ir/api/v1/open/cars/?brand=saipa&min_price=500000000&limit=10"
{
  "total": 214,
  "limit": 2,
  "offset": 0,
  "results": [
    {
      "id": 17,
      "brand": "سایپا", "brand_key": "saipa",
      "model": "شاهین", "model_key": "shahin",
      "trim": "G اتوماتیک", "year": 1404,
      "price_toman": 1250000000,
      "prev_price_toman": 1240000000,
      "change_toman": 10000000,
      "change_pct": 0.81,
      "updated_at": "2026-11-17T08:30:00+00:00"
    }
  ],
  "attribution": { "name": "هدهد ویژن", "url": "https://hodhodvision.ir/", "required": true }
}

هشدار: قیمت خودرو برآورد بازار آزاد است و قیمت قطعی معامله نیست. هر روز ساعت ۱۲ ظهر به وقت تهران به‌روز می‌شود.

مشخصات ماشین‌خوان همه‌ی API‌ها: https://hodhodvision.ir/api/v1/open/openapi.json (OpenAPI 3.1).

گرفتن کلید API خبر · API رایگان قیمت · OpenAPI

پرسش‌های متداول

API خبر هدهد ویژن چیست؟

یک وب‌سرویس JSON است که خبرهای تازه فارسی هدهد ویژن را در چارچوبی که خودتان می‌سازید (دسته، استان، شهر، موضوع، کلیدواژه) به سایت یا اپ شما می‌رساند. هر مشترک یک کلید اختصاصی دارد و هر کلید فقط به یک آدرس (یک دامنه یا یک IP) وصل می‌شود.

پلن‌ها و قیمت‌ها چقدر است؟

تست رایگان یک‌روزه، هفتگی ۵ هزار تومان، ماهانه ۲ میلیون تومان، سه‌ماهه ۶ میلیون تومان و شش‌ماهه ۱۲ میلیون تومان. همه‌ی پلن‌ها از نظر امکانات یکسان‌اند و فقط مدت دسترسی فرق دارد.

چطور کلید می‌گیرم؟

پلن را انتخاب کنید، فیلترهای خبری و آدرس سایت یا IP را وارد کنید، حساب (نام کاربری و رمز) بسازید و پرداخت را در درگاه کامل کنید. کلید بلافاصله پس از پرداخت موفق در همان صفحه نمایش داده می‌شود.

چرا فقط یک دامنه یا یک IP؟

برای جلوگیری از فروش یا اشتراک کلید بین چند سایت. اگر کلید از آدرسی غیر از آدرس ثبت‌شده فراخوانی شود رد می‌شود و ثبت می‌گردد؛ آدرس دوم برای یک کلید پذیرفته نمی‌شود و یک آدرسِ فعال هم برای دو مشترک ثبت نمی‌شود.

کلید را می‌توانم در جاوااسکریپت مرورگر بگذارم؟

نه. فراخوانی باید از سرور شما انجام شود؛ درخواست‌هایی که هدر Origin مرورگر دارند رد می‌شوند تا کلید شما لو نرود. سرور شما خبرها را می‌گیرد و به صفحه‌های خودتان می‌دهد.

اگر سایتم پشت CDN مثل کلودفلر باشد چه؟

فراخوانی از سرور شما با IP همان سرور انجام می‌شود؛ اگر IP مبدأ با رکورد DNS دامنه یکی نیست، حالت IP را انتخاب کنید و IP خروجی سرور را وارد کنید.