REST API جستجو

نتایج جستجو از یک مسیر REST داخلی وردپرس می‌آید. این مسیر برای استفاده‌ی خود ویجت ساخته شده، ولی عمومی و مستند است؛ پس می‌توانید برای اپلیکیشن، ابزارک سفارشی یا اسکریپت خودتان هم از آن استفاده کنید.

نقطه‌ی پایان

GET https://example.com/wp-json/wgcr/v1/search

پارامترها

اعتبارسنجی q: اگر رشته نباشد یا طول آن پس از trim کمتر از 2 نویسه باشد، پاسخ خطای rest_invalid_param برمی‌گردد.

شکل پاسخ

پاسخ یک آرایه‌ی JSON از نتیجه‌هاست:

[
	{
		"id": 42,
		"title": "آموزش ساخت ویجت المنتور",
		"link": "https://example.com/?p=42",
		"thumb": "https://example.com/wp-content/uploads/2026/09/cover-150x150.jpg",
		"excerpt": "در این آموزش از صفر تا صد ساخت یک ویجت سفارشی را می‌بینید…",
		"date": "2026/09/26"
	}
]

هدرهای صفحه‌بندی

فقط وقتی page بزرگ‌تر از صفر باشد:

نمونه‌ها

یک درخواست، چهار زبان برنامه‌نویسی؛ زبانه‌ی مناسب را انتخاب کنید.

curl -s "https://example.com/wp-json/wgcr/v1/search?q=آموزش&limit=5&type=post"

# با صفحه‌بندی و خواندن هدرهای شمارش
curl -sD - -o /dev/null "https://example.com/wp-json/wgcr/v1/search?q=آموزش&limit=12&page=2" | grep -i "^x-wp"

const url = new URL('/wp-json/wgcr/v1/search', window.location.origin);
url.searchParams.set('q', 'آموزش');
url.searchParams.set('limit', '8');
url.searchParams.set('page', '1');

const res = await fetch(url, { headers: { Accept: 'application/json' } });
const items = await res.json();
const total = Number(res.headers.get('X-WP-Total') || 0);
const pages = Number(res.headers.get('X-WP-TotalPages') || 0);

items.forEach((item) => {
	console.log(item.title, item.link, item.thumb);
});

url.searchParams.set('terms', 'category:12,category:18');
url.searchParams.set('terms_op', 'include');
url.searchParams.set('orderby', 'date');
url.searchParams.set('order', 'DESC');

url.searchParams.set('template', '1482');

وقتی template معتبر باشد، هر نتیجه علاوه بر فیلدهای بالا یک فیلد html دارد که خروجی رندرشده‌ی همان قالب برای همان نوشته است. اگر قالب پیش‌نویس باشد یا محتوای قابل‌مشاهده نسازد، html برنمی‌گردد.

رفتار سمت سرور

1. q، type، limit و page پاک‌سازی و محدود می‌شوند
2. آرگومان‌های WP_Query ساخته می‌شوند (publish، بدون رمز، بدون found_rows وقتی page < 1)
3. فیلترهای orderby، date، terms و query_id اعمال می‌شوند
4. فیلترهای wgcr_search_query_args اجرا می‌شوند
5. کوئی اجرا و در صورت نیاز نوشته‌های چسبنده به اول منتقل می‌شوند
6. اگر template داده شده باشد، خروجی قالب برای هر نتیجه ساخته می‌شود
7. پاسخ با هدرهای صفحه‌بندی برمی‌گردد

کدهای پاسخ

محدودسازی و بهینه‌سازی

• کش: مسیر /wp-json/ را از کش کامل صفحه بیرون بگذارید؛ وگرنه نتیجه‌ی جستجوی یک کاربر به کاربر دیگر داده می‌شود.
• نرخ درخواست: افزونه هیچ محدودسازی نرخ (rate limit) داخلی ندارد. اگر سایت پرمراجعه است، در سطح سرور (مثلاً Nginx یا WAF) برای /wp-json/wgcr/v1/search محدودیت بگذارید.
• سقف نتایج: با ثابت WGCR_SEARCH_MAX_RESULTS در wp-config.php می‌توانید سقف 50 را تغییر دهید؛ این مقدار هم در ویجت، هم در شورت‌کد و هم در REST اعمال می‌شود.

define( 'WGCR_SEARCH_MAX_RESULTS', 20 );