API reference

Web search (preview)

Web search results from Google, for your own program. This is a preview for Acacus testers only: it is not part of the public API, and accounts that are not testers get a 403.

Request

curl https://acacus.ly/v1/search \
  -H "Authorization: Bearer $ACACUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Central Bank of Libya exchange rate", "num": 5, "gl": "ly", "hl": "en"}'

• query (required): the search text, up to 400 characters.
• num (optional): how many results, from one to ten. The default is six.
• gl (optional): two-letter country, default ly.
• hl (optional): result language, such as ar or en. Default: Arabic if the query is in Arabic, else English.

Response

{
  "object": "search.results",
  "query": "Central Bank of Libya exchange rate",
  "source": "web",
  "attribution": "Web search results. Each result belongs to the site at its url; the title and snippet are that site's. Source: Google Search, via Serper.",
  "results": [
    {
      "title": "Page title",
      "url": "https://example.com/page",
      "snippet": "A short extract from the page.",
      "position": 1,
      "source": "web"
    }
  ],
  "usage": { "credits": 1, "cached": false, "cost_lyd": 0.03 }
}

Every result is a web search result and belongs to the site at its url. If you show or pass on a result, keep its URL and say where it came from; don't present the results as your own data or as Acacus's. Each result has title, url, snippet, position and source (always web).

Price

Each call is charged from your API balance in LYD. A search repeated within ten minutes is answered from memory and costs nothing (usage.cached is true). A call that fails is not charged. Without enough balance the answer is 402.

Errors and limits

• 403 SEARCH_TESTERS_ONLY: your account is not a tester.
• 402 INSUFFICIENT_BALANCE: top up your balance.
• 429: at most 30 requests a minute; wait for Retry-After seconds.
• 502 SEARCH_UNAVAILABLE: the search service didn't answer; nothing was charged.
• 404: web search is not switched on on this server.

Next steps