مستندات API هدهد ویژن
راهنمای ساده و کامل API خبر و API رایگان قیمت ارز، طلا و خودرو: شروع سریع در ۵ دقیقه، توضیح کلید و آدرس مجاز، نمونه کد Python، PHP، Node و وردپرس و رفع خطاها.
شروع سریع؛ اولین خبر در ۵ دقیقه
اگر تازه با API کار میکنید نگران نباشید: API یعنی یک آدرس اینترنتی که بهجای صفحهی وب، داده میدهد. شما از سرور خودتان به آن آدرس درخواست میفرستید و خبرها را به شکل JSON (متن ساختاریافته) تحویل میگیرید.
- کلید بگیرید: در صفحهی «API خبر» پلن «تست رایگان» را انتخاب کنید، مراحل را کامل کنید و کلیدی شبیه hk_live_… بگیرید. کلید فقط یک بار نمایش داده میشود؛ همان لحظه ذخیرهاش کنید.
- آدرس مجاز را درست وارد کنید: هنگام خرید باید بگویید فراخوانی از کجا انجام میشود: دامنهی سایتتان (example.ir) یا IP سرورتان. کلید فقط از همین آدرس کار میکند.
- از سرور خودتان این دستور را بزنید: کلید را جایگزین YOUR_KEY کنید و دستور زیر را روی سرور (نه روی مرورگر) اجرا کنید.
- پاسخ را ببینید: اگر همهچیز درست باشد کدِ ۲۰۰ و فهرست خبرها را میگیرید. اگر خطا گرفتید به بخش «خطاها و راهحل» بروید؛ هر خطا یک راهحل روشن دارد.
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 بزرگتری دارد. |
| cursor | seq آخرین خبری که گرفتهاید. دفعهی بعد آن را در 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 | تعداد خبر در همین پاسخ |
| cursor | seq آخرین خبر؛ دفعهی بعد بهعنوان since بفرستید |
| has_more | true یعنی خبر جدیدتری هم هست؛ بلافاصله دوباره بپرسید. 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/"الگوی درست همگامسازی خبر
اگر میخواهید همهی خبرهای تازه را در پایگاهدادهی خودتان داشته باشید، این چرخه را اجرا کنید:
- cursor را بخوانید: بار اول 0 است. بعد از هر دور آن را در فایل یا پایگاهداده ذخیره کنید تا با ریاستارت برنامه از نو شروع نشود.
- درخواست بزنید: GET /feed/?since=CURSOR&limit=50
- خبرها را ذخیره کنید و cursor را بهروز کنید: cursor پاسخ را ذخیره کنید.
- اگر 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"
}
}| HTTP | code | یعنی چه؟ | چه کنم؟ |
|---|---|---|---|
| 401 | missing_key | کلید فرستاده نشده | هدر X-API-Key را اضافه کنید. |
| 401 | invalid_key | کلید اشتباه یا باطلشده | کلید را از پنل بررسی کنید؛ اگر کلید جدید ساختهاید قبلی باطل است. |
| 403 | ip_mismatch | IP فراخوان با IP ثبتشده فرق دارد | در پاسخ your_ip را ببینید؛ از همان سرور صدا بزنید یا با پشتیبانی آدرس را عوض کنید. |
| 403 | ip_not_in_dns | IP فراخوان جزو IPهای DNS دامنه نیست | از سروری صدا بزنید که دامنه به آن اشاره میکند، یا بهجای دامنه IP ثبت کنید. |
| 403 | dns_unresolved | دامنهی ثبتشده DNS ندارد | رکورد A دامنه را بررسی کنید. |
| 403 | dns_too_many_ips | دامنه بیش از ۴ IP دارد | حالت IP را استفاده کنید. |
| 403 | browser_not_allowed | درخواست از مرورگر آمده | فراخوانی را به سرور خودتان ببرید. |
| 403 | subscription_expired | اشتراک تمام شده | از صفحهی API خبر تمدید کنید؛ کلید عوض نمیشود. |
| 403 | suspended | کلید مسدود شده | با پشتیبانی تماس بگیرید. |
| 404 | not_found | این خبر در چارچوب شما نیست | شناسه یا فیلترها را بررسی کنید. |
| 429 | rate_limited | بیش از ۱۲۰ درخواست در دقیقه | هدر Retry-After را صبر کنید و تعداد درخواست را کم کنید. |
| 429 | blocked | تلاشهای اشتباه زیاد از این IP | ده دقیقه صبر کنید. |
مدیریت اشتراک: تمدید، فیلتر، کلید جدید
- ورود: در صفحهی API خبر با نام کاربری و رمزتان وارد شوید؛ بخش «اشتراکهای من» باز میشود.
- تمدید: دکمهی «تمدید» → پلن را انتخاب کنید. مدت جدید به انتهای اشتراک فعلی اضافه میشود و کلید عوض نمیشود.
- ویرایش فیلتر: رایگان و بیدرنگ اعمال میشود. فقط آدرس مجاز قابل تغییر نیست.
- کلید جدید: اگر کلید لو رفت بسازید. کلید قبلی همان لحظه باطل میشود؛ روزی حداکثر ۳ بار.
API رایگان قیمت ارز، طلا، سکه و خودرو
این API کلید و ثبتنام نمیخواهد و از مرورگر هم قابل فراخوانی است (CORS آزاد). تنها شرط: نام «هدهد ویژن» را با پیوند کنار قیمتها نشان دهید. حداکثر ۱۲۰ درخواست در دقیقه برای هر IP؛ نتیجه را حداقل یک دقیقه کش کنید.
- درخواست بزنید: برای دلار: GET https://hodhodvision.ir/api/v1/open/prices/?keys=usd
- مقدار را بخوانید: در results[0].value قیمت و در unit واحد (تومان یا دلار) است.
- منبع را بنویسید: کنار قیمت بنویسید: «منبع: هدهد ویژن» با پیوند به 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 خروجی سرور را وارد کنید.