Search the web (JSON body)

curl --request POST \
  --url https://api.andiai.com/api/v1/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "q": "best italian restaurants near me",
  "limit": 10,
  "city": "San Francisco",
  "state": "California",
  "countryCode": "US",
  "latitude": 37.7794,
  "longitude": -122.4176
}
'

import requests

url = "https://api.andiai.com/api/v1/search"

payload = {
    "q": "best italian restaurants near me",
    "limit": 10,
    "city": "San Francisco",
    "state": "California",
    "countryCode": "US",
    "latitude": 37.7794,
    "longitude": -122.4176
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    q: 'best italian restaurants near me',
    limit: 10,
    city: 'San Francisco',
    state: 'California',
    countryCode: 'US',
    latitude: 37.7794,
    longitude: -122.4176
  })
};

fetch('https://api.andiai.com/api/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.andiai.com/api/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'q' => 'best italian restaurants near me',
    'limit' => 10,
    'city' => 'San Francisco',
    'state' => 'California',
    'countryCode' => 'US',
    'latitude' => 37.7794,
    'longitude' => -122.4176
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.andiai.com/api/v1/search"

	payload := strings.NewReader("{\n  \"q\": \"best italian restaurants near me\",\n  \"limit\": 10,\n  \"city\": \"San Francisco\",\n  \"state\": \"California\",\n  \"countryCode\": \"US\",\n  \"latitude\": 37.7794,\n  \"longitude\": -122.4176\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.andiai.com/api/v1/search")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"best italian restaurants near me\",\n  \"limit\": 10,\n  \"city\": \"San Francisco\",\n  \"state\": \"California\",\n  \"countryCode\": \"US\",\n  \"latitude\": 37.7794,\n  \"longitude\": -122.4176\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.andiai.com/api/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"q\": \"best italian restaurants near me\",\n  \"limit\": 10,\n  \"city\": \"San Francisco\",\n  \"state\": \"California\",\n  \"countryCode\": \"US\",\n  \"latitude\": 37.7794,\n  \"longitude\": -122.4176\n}"

response = http.request(request)
puts response.read_body

{
  "results_type": "<string>",
  "answer": "<string>",
  "type": "<string>",
  "title": "<string>",
  "results": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "metrics": {
    "query": "<string>",
    "intent": "<string>",
    "timestamp": "<string>",
    "duration": 123,
    "queries_executed": 123,
    "api_requests_count": 123,
    "results_returned": 123,
    "total_results_found": 123,
    "queries_provided": 123,
    "queries_truncated": 123,
    "cached": true,
    "cache_age_seconds": 123,
    "cost_dollars": 123,
    "effort": "low",
    "response_time_ms": 123
  },
  "correctedQuery": "<string>",
  "related_searches": [
    "<string>"
  ],
  "topics": [
    "<string>"
  ],
  "related_topics": [
    "<string>"
  ],
  "infobox": {
    "heading": "<string>",
    "source": "<string>",
    "items": [
      {
        "label": "<string>",
        "value": "<string>"
      }
    ]
  },
  "disambiguation": {
    "query": "<string>",
    "message": "<string>",
    "options": [
      {
        "title": "<string>",
        "text": "<string>",
        "url": "<string>"
      }
    ]
  },
  "aiSummary": {
    "text": "<string>",
    "generatedAt": "2023-11-07T05:31:56Z",
    "model": "<string>",
    "mode": "pregen"
  },
  "safeSearch": {
    "requested": "off",
    "applied": "off"
  },
  "videos": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "images": [
    {
      "title": "<string>",
      "link": "<string>",
      "image": "<string>",
      "source": "<string>",
      "type": "image",
      "thumbnail": "<string>",
      "width": "<string>",
      "height": "<string>"
    }
  ],
  "news": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "places": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "profiles": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "social": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "academic": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "weather": {
    "location": {
      "name": "<string>",
      "country": "<string>",
      "coordinates": {
        "latitude": 123,
        "longitude": 123
      }
    },
    "temperature": 123,
    "units": "metric",
    "description": "<string>",
    "feelsLike": 123,
    "humidity": 123,
    "windSpeed": 123,
    "windDirection": 123,
    "pressure": 123,
    "icon": "<string>",
    "cloudiness": 123,
    "visibility": 123,
    "timestamp": 123
  },
  "calculation": {
    "expression": "<string>",
    "result": "<string>",
    "rawResult": "<unknown>"
  }
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

POST

api

Search the web (JSON body)

curl --request POST \
  --url https://api.andiai.com/api/v1/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "q": "best italian restaurants near me",
  "limit": 10,
  "city": "San Francisco",
  "state": "California",
  "countryCode": "US",
  "latitude": 37.7794,
  "longitude": -122.4176
}
'

import requests

url = "https://api.andiai.com/api/v1/search"

payload = {
    "q": "best italian restaurants near me",
    "limit": 10,
    "city": "San Francisco",
    "state": "California",
    "countryCode": "US",
    "latitude": 37.7794,
    "longitude": -122.4176
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    q: 'best italian restaurants near me',
    limit: 10,
    city: 'San Francisco',
    state: 'California',
    countryCode: 'US',
    latitude: 37.7794,
    longitude: -122.4176
  })
};

fetch('https://api.andiai.com/api/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.andiai.com/api/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'q' => 'best italian restaurants near me',
    'limit' => 10,
    'city' => 'San Francisco',
    'state' => 'California',
    'countryCode' => 'US',
    'latitude' => 37.7794,
    'longitude' => -122.4176
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.andiai.com/api/v1/search"

	payload := strings.NewReader("{\n  \"q\": \"best italian restaurants near me\",\n  \"limit\": 10,\n  \"city\": \"San Francisco\",\n  \"state\": \"California\",\n  \"countryCode\": \"US\",\n  \"latitude\": 37.7794,\n  \"longitude\": -122.4176\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.andiai.com/api/v1/search")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"best italian restaurants near me\",\n  \"limit\": 10,\n  \"city\": \"San Francisco\",\n  \"state\": \"California\",\n  \"countryCode\": \"US\",\n  \"latitude\": 37.7794,\n  \"longitude\": -122.4176\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.andiai.com/api/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"q\": \"best italian restaurants near me\",\n  \"limit\": 10,\n  \"city\": \"San Francisco\",\n  \"state\": \"California\",\n  \"countryCode\": \"US\",\n  \"latitude\": 37.7794,\n  \"longitude\": -122.4176\n}"

response = http.request(request)
puts response.read_body

{
  "results_type": "<string>",
  "answer": "<string>",
  "type": "<string>",
  "title": "<string>",
  "results": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "metrics": {
    "query": "<string>",
    "intent": "<string>",
    "timestamp": "<string>",
    "duration": 123,
    "queries_executed": 123,
    "api_requests_count": 123,
    "results_returned": 123,
    "total_results_found": 123,
    "queries_provided": 123,
    "queries_truncated": 123,
    "cached": true,
    "cache_age_seconds": 123,
    "cost_dollars": 123,
    "effort": "low",
    "response_time_ms": 123
  },
  "correctedQuery": "<string>",
  "related_searches": [
    "<string>"
  ],
  "topics": [
    "<string>"
  ],
  "related_topics": [
    "<string>"
  ],
  "infobox": {
    "heading": "<string>",
    "source": "<string>",
    "items": [
      {
        "label": "<string>",
        "value": "<string>"
      }
    ]
  },
  "disambiguation": {
    "query": "<string>",
    "message": "<string>",
    "options": [
      {
        "title": "<string>",
        "text": "<string>",
        "url": "<string>"
      }
    ]
  },
  "aiSummary": {
    "text": "<string>",
    "generatedAt": "2023-11-07T05:31:56Z",
    "model": "<string>",
    "mode": "pregen"
  },
  "safeSearch": {
    "requested": "off",
    "applied": "off"
  },
  "videos": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "images": [
    {
      "title": "<string>",
      "link": "<string>",
      "image": "<string>",
      "source": "<string>",
      "type": "image",
      "thumbnail": "<string>",
      "width": "<string>",
      "height": "<string>"
    }
  ],
  "news": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "places": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "profiles": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "social": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "academic": [
    {
      "title": "<string>",
      "link": "<string>",
      "desc": "<string>",
      "source": "<string>",
      "type": "website",
      "date": "<string>",
      "dateModified": "<string>",
      "image": "<string>",
      "snippet": "<string>",
      "answer": "<string>",
      "extracts": [
        "<string>"
      ],
      "contentType": "<string>",
      "reader": {},
      "contentSafety": {
        "rating": "safe",
        "safeSearchApplied": true
      },
      "bang": "<string>",
      "queryIndices": [
        123
      ],
      "seeAlso": [
        {
          "title": "<string>",
          "url": "<string>",
          "source": "<string>"
        }
      ]
    }
  ],
  "weather": {
    "location": {
      "name": "<string>",
      "country": "<string>",
      "coordinates": {
        "latitude": 123,
        "longitude": 123
      }
    },
    "temperature": 123,
    "units": "metric",
    "description": "<string>",
    "feelsLike": 123,
    "humidity": 123,
    "windSpeed": 123,
    "windDirection": 123,
    "pressure": 123,
    "icon": "<string>",
    "cloudiness": 123,
    "visibility": 123,
    "timestamp": 123
  },
  "calculation": {
    "expression": "<string>",
    "result": "<string>",
    "rawResult": "<unknown>"
  }
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

Authorizations

x-api-key

string

header

required

API key from the API Console.

Body

application/json

string

required

Search query string. Same semantics as the GET q parameter.

limit

integer

default:10

Maximum number of results to return.

Required range: 1 <= x <= 100

offset

integer

default:0

Number of results to skip for pagination.

Required range: x >= 0

searchMode

enum<string>

default:auto

Search effort control. auto (default) sets the effort per query automatically — simple lookups resolve fast, complex questions get deeper treatment. The fixed modes pin an effort level: low-cost caps the work done per request for budget-constrained callers. fast returns results in about 1.2 seconds. balanced is everyday web search, about 3–4 seconds. deep searches from multiple angles with spell correction, about 6.5 seconds. exhaustive is Andi's most thorough mode: more sources and more time, up to about 15 seconds; for a question with several parts or steps it searches each part. Deeper modes add query expansion, follow-up searches fanned out from initial results, and stronger reranking. Requests are billed on outcome-based pricing (see metrics.cost_dollars).

Available options:

auto,

low-cost,

fast,

balanced,

deep,

exhaustive

effort

enum<string>

Thoroughness dial, independent of searchMode: low favors speed, medium is balanced, high searches from multiple angles with spell correction, max gives the most complete results and also searches each part of a question that has several parts or steps — the same tiers as pinning searchMode to fast, balanced, deep, and exhaustive respectively. An explicit searchMode always wins over effort. With the default auto mode, an explicit effort pins its equivalent mode. Omit for the adaptive default. Invalid values return a 400 listing the valid tiers.

Available options:

low,

medium,

high,

max

reranker

enum<string>

default:auto

Semantic reranker size hint. small is the lightest and fastest; medium and above apply stronger relevance scoring but need a deeper searchMode and may be clamped by the request's time and cost budget (for example, xl needs deep or exhaustive). auto (default) selects a tier automatically based on the query and search mode.

Available options:

auto,

small,

medium,

large,

xl

intent

string

Force a specific search intent. When not set, the API auto-detects intent from the query. Accepts common aliases like search, news, video, images, weather, wiki, code, recipe, place, time, and others.

format

enum<string>

default:json

Response format. json returns a JSON object. context returns results as markdown text, suitable for passing to language models.

Available options:

json,

context

metadata

enum<string>

default:basic

Level of metadata to include. basic includes standard search metrics. full includes extended metadata with content type details and reader data on results.

Available options:

basic,

full

extracts

boolean

default:false

Include text extracts from result pages in the response. Also returned by default with metadata=full.

content

boolean

default:false

Include each result's full page text, in reader.markdown (or reader.content when the page has no markdown version). Adds time and cost; deeper modes allow more time.

enrichContent

boolean

default:false

deprecated

Deprecated alias of content.

maxContentLength

integer

Maximum number of characters of page text to return per result. Only applies when content is true.

timeout

integer

Target time in milliseconds for ranked results (1000–30000). It is a target, not a hard ceiling. Omit it for the mode's normal speed; a larger value (e.g. 30000) lets slower sources run longer, so deep/exhaustive searches can take close to that long. The search may run a little past it when it needs a moment more to return a useful page. Requested page text (content/extracts) is fetched afterward, on top of the target. Values below 1000 are raised to 1000; values above 30000 are lowered to 30000; 0, empty or non-numeric values are ignored. With searchMode=auto (the default), a timeout steps the resolved mode down to the richest one that fits it. An explicit searchMode is always honored.

Required range: 1000 <= x <= 30000

safe

enum<string>

default:off

Safe search filtering level. off disables filtering, moderate filters most explicit content, strict applies maximum filtering.

Available options:

off,

moderate,

strict

country

string

default:US

Two-letter ISO 3166-1 country code to localize results.

sourceCountry

string

Two-letter ISO 3166-1 country code to restrict results to sources from this country. Unlike country, which biases results by locale, sourceCountry excludes results from other countries.

language

string

default:en

Preferred language for results, as an ISO 639-1 code.

units

enum<string>

Unit system for weather and calculation results. Defaults based on the country parameter — imperial for US, metric for all other countries.

Available options:

metric,

imperial

noCache

boolean

default:false

Bypass cached results and fetch fresh data.

dateRange

enum<string>

Relative date range filter for results.

Available options:

day,

week,

month,

year,

24h,

7d,

30d,

90d,

1y

dateFrom

string<date>

Filter results published on or after this date. Format: YYYY-MM-DD.

dateTo

string<date>

Filter results published on or before this date. Format: YYYY-MM-DD.

includeDomains

string

Comma-separated list of domains to restrict results to. Supports wildcards (*.example.com).

excludeDomains

string

Comma-separated list of domains to exclude from results. Supports wildcards.

includeTerms

string

Comma-separated terms that must appear in results.

excludeTerms

string

Comma-separated terms to exclude from results.

parseOperators

boolean

default:true

Parse query operators (like site:, filetype:, intitle:) from the query string. When disabled, the query is treated as literal text.

linkFormat

enum<string>

default:link

Field name for result URLs. Use url to receive the URL field as url instead of the default link. Only affects the /search endpoint.

Available options:

link,

url

imageFormat

enum<string>

default:long

Field naming for image results. long (default) uses full field names. short uses abbreviated field names.

Available options:

short,

long

filetype

string

Filter results by file type.

intitle

string

Filter results to pages with this term in the title.

inurl

string

Filter results to pages with this term in the URL.

intext

string

Filter results to pages with this term in the body text.

latitude

number

Latitude in decimal degrees. Sent in the body to keep coordinates out of HTTP access logs.

longitude

number

Longitude in decimal degrees.

accuracy

number

Location accuracy in meters.

city

string

City name for location-aware queries.

state

string

State or region name.

countryCode

string

Two-letter ISO 3166-1 country code for the caller's location.

postalCode

string

Postal or ZIP code.

timezone

string

IANA timezone, for example America/Los_Angeles.

location

string

Display name for the caller's location, for example "San Francisco, CA".

Response

Search results. JSON by default; LLM-ready markdown with YAML frontmatter when format=context.

results_type

string

required

The type of results returned (e.g., Search, News, Weather, Calculator). Determines which optional response sections are present.

answer

string

required

Instant answer for the query when one is found — for example a definition, a weather line or a calculation — otherwise an empty string. On news feeds, a short summary of the headlines when available.

type

string

required

Same as results_type. Indicates the category of results.

title

string

required

Your query text (for a news feed, the feed's description).

results

object[]

required

Array of search results.

Show child attributes

metrics

object

required

Search performance metrics. Always included in the response.

Show child attributes

correctedQuery

string

Spell-corrected query. Present when a misspelling in the original query is detected and corrected — any mode can return it; deep and exhaustive modes run the strongest spell correction.

Related search suggestions. Present on some queries.

topics

string[]

Related topics. Present on some queries.

Overview

Endpoints

Search the web (JSON body)

Authorizations

Body

Response