API guide#

Every Searpa search feature, web, images, news, videos, maps, translate, instant answers, knowledge cards, suggestions and provider status, is available programmatically over a JSON API. The same service functions back the API and the website, so both always return the same results.

The API is built with Django REST Framework and mounted under /api/v1/.

The public API is a self-hosted feature. It ships with the open-source engine and is available on any instance you run yourself. The hosted service at searpa.eu does not expose it, so to use the API, run your own instance and create a key there.

Base URL#

https://search.example.com/api/v1/

The examples below use search.example.com as a stand-in, replace it with your own instance’s host.

At a glance#

• Authentication: every request needs a per-user API key.
• Stateless: the options the website keeps in a cookie (engine, safe search, language, time range, page) are plain query parameters, so a request is fully described by its URL.
• Rate limited: per key, with a burst and a daily cap.
• JSON only: every endpoint returns JSON.

A first request#

curl -H "Authorization: Api-Key searpa_sk_<prefix>.<secret>" \
  "https://search.example.com/api/v1/web/?q=climate&lang=en"

In this guide#

The in-app developer page at /api/ links to this documentation and to the key manager. An Insomnia collection of the endpoints ships in the repository (scripts/searpa-api.insomnia.json).