واجهة برمجة تطبيقات الإكمال التلقائي لبحث Google - اقتراحات كلمات مفتاحية فورية

#What Query Suggest solves

Autocomplete shows real user search intents as you type. Use it to reduce zero-result queries, guide users to popular paths, and expand content/keyword ideas by language and locale.

#Endpoint & when to use it

#POST /v1/google/search/autocomplete/autocomplete — Query Suggest (Autocomplete)

• Best for: Search bars, filters, onboarding wizards, SEO ideation, merchandising queries.
• How it works: You pass a prefix (q) and optional language (hl), we return ranked suggestions.
• Typical use: Client debounces keystrokes (e.g., 120–200ms), calls backend which proxies this endpoint.

#Quick start

curl -X POST "https://api.yeb.to/v1/google/search/autocomplete/autocomplete" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "q": "best electric cars", "hl": "en" }'

// JS Fetch example
fetch('https://api.yeb.to/v1/google/search/autocomplete/autocomplete', {
  method: 'POST',
  headers: {
    'X-API-Key': '<YOUR_API_KEY>',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({ q: 'best electric cars', hl: 'en' })
})
.then(r => r.json())
.then(console.log)
.catch(console.error);

#Parameters that actually matter

#Reading & acting on responses

{
  "query": "best electric cars",
  "lang": "en",
  "cnt_results": 5,
  "suggestions": [
    "best electric cars 2025",
    "best electric cars range",
    "best electric cars under 40k",
    "best electric cars for families",
    "best electric cars lease deals"
  ]
}

• query — the normalized input we processed (useful for debugging/caching).
• lang — effective language used; verify it matches your UI.
• cnt_results — fast guard for empty states and rate-limiting logic.
• suggestions[] — ordered phrases you can render directly in your typeahead.

#Recommended actions

• Debounce & cache: 120–200ms debounce per user; cache last 20 prefixes per session (and server-side LRU for hot prefixes).
• Empty state UX: If cnt_results = 0, show recent searches or curated shortcuts.
• Locale-aware: Tie hl to user’s language selector; don’t infer from IP unless UI also changes.

#Practical recipes

• Typeahead: On keypress, call with q, render the top 5 suggestions; accept arrow/enter to complete.
• SEO ideation: Precompute common stems (e.g., “best <category>”), store suggestions for content planning.
• Facet helpers: In complex search, merge suggestions with your own filters to guide users to valid queries.
• Localize: Switch hl with the app locale to keep suggestions culturally relevant.

#Troubleshooting & field notes

1. “Missing q” (400): Ensure you send q as a non-empty string; trim before sending.
2. Unauthorized (401): Invalid/expired key or wrong header (X-API-Key required).
3. Few/zero results: Try a longer prefix or switch hl to match your audience language.
4. Rate limits: Implement client debounce + server-side caching. Backoff on repeated requests for the same prefix.

#API Changelog