Searchia

JSON API

Making a request

Send a POST to /api with a JSON body.

POST /api
Content-Type: application/json

{
  "query": "searchia",
  "type": "web",
  "page": 0
}

Request fields

Field Type Description
query string required. the search query.
type string optional, defaults to web. one of web, images, news.
page integer optional, defaults to 0. the result offset. 0 is the first page; increment to paginate. no upper bound.

Examples

curl

curl -X POST https://www.searchia.com/api \
  -H "Content-Type: application/json" \
  -d '{"query":"searchia","type":"web","page":0}'

JavaScript

const res = await fetch("https://www.searchia.com/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "searchia", type: "web", page: 0 }),
});

const data = await res.json();
console.log(data.results);

Responses

Every successful response returns an object with query, type, page, along with more_results_available and the main results object.

Web (type: "web")

results is an object grouping the different result kinds. Fields are null when absent for a given query. 

{
  "query": "searchia",
  "type": "web",
  "page": 0,
  "badResults": false,
  "more_results_available": true,
  "results": {
    "web": {
      "results": [
        {
          "title": "…",
          "url": "https://…",
          "description": "…",
          "age": "…",
          "meta_url": { "hostname": "…", "favicon": "…" },
          "profile": { "name": "…", "img": "…" },
          "thumbnail": { "src": "…" },
          "deep_results": { "buttons": [{ "title": "…", "url": "…" }] },
          "cluster": [{ "title": "…", "label": "…", "url": "…", "description": "…" }]
        }
      ]
    },
    "news": { "results": [ … ] },
    "videos": { "results": [ … ] },
    "discussions": { "results": [ … ] },
    "faq": { "results": [ … ] },
    "infobox": { "results": [ … ] },
    "rich": [ … ],
    "qanda": …,
    "locations": …,
    "images": …,
    "mixed": [ … ]
  }
}

rich carries instant answers (calculator, weather, currency, crypto, timezones, unit conversions, and more), each tagged with a subtype. mixed mirrors the upstream ordering of the main column.

Images (type: "images")

{
  "query": "teto",
  "type": "images",
  "page": 0,
  "more_results_available": true,
  "results": [
    {
      "title": "…",
      "url": "https://…",
      "source": "…",
      "thumbnail": "https://…",
      "properties": { "url": "https://…", "width": 1200, "height": 800 },
      "meta_url": { "hostname": "…", "favicon": "…" }
    }
  ]
}

News (type: "news")

{
  "query": "elections",
  "type": "news",
  "page": 0,
  "more_results_available": true,
  "results": [
    {
      "title": "…",
      "url": "https://…",
      "description": "…",
      "age": "…",
      "meta_url": { "hostname": "…", "favicon": "…" },
      "profile": { "name": "…", "img": "…" },
      "thumbnail": { "src": "…" },
      "is_live": false
    }
  ]
}

Pagination

Start at page: 0. If the response has more_results_available: true, request page: 1, then 2, and so on. When it is false there is nothing more to fetch.

Errors

Errors are returned as JSON with an error string and a matching status code.

Status Meaning
400 Bad body, missing query, unknown type, or invalid page.
502 The upstream search failed. 
{ "error": "missing required field: query" }

Autocomplete (/suggest)

Send a GET to /suggest with a partial query.

GET /suggest?q=weath

Query parameters

Param type description
q string Required. The partial query to complete, up to 100 characters.

Response

The suggestions field is an ordered array. Plain completions carry just a query; rich entities (people, places, and more) set entity and add the best-effort fields below. 

{
  "suggestions": [
    { "query": "weather" },
    { "query": "weather radar" },
    {
      "query": "elon musk",
      "entity": true,
      "name": "Elon Musk",
      "desc": "businessman and entrepreneur (born 1971)",
      "category": "person",
      "img": "https://imgs.search.brave.com/…"
    }
  ]
}
field type description
query string the suggested query. always present.
entity boolean true on entity suggestions; absent otherwise.
name string the entity's display name.
desc string a short description.
category string e.g. person, place.
img string thumbnail URL, when one is available.

curl

curl "https://www.searchia.com/suggest?q=weath"