Response format

The API returns JSON by default. The format=context option returns markdown with YAML frontmatter instead — see context format below.

The results_type field tells you the shape of the response. Use it to determine which arrays and objects are present — for example, results_type: "Weather" means a weather object is included.

Top-level fields

Field	Type	Always present	Description
`results_type`	string	Yes	Category of results (e.g., `Search`, `News`, `Weather`, `Entity`, `Calculator`)
`answer`	string	Yes	Generated answer for the query (may be empty)
`type`	string	Yes	Same as `results_type`
`title`	string	Yes	Title summarizing the search results
`results`	array	Yes	Search results
`metrics`	object	Yes	Search performance and cost metrics
`safeSearch`	object	No	Echo of safe-search state: `{requested, applied}`. Present on cache misses. Use this to confirm your `safe` parameter was honored.
`correctedQuery`	string	No	Spell-corrected query, when a correction was detected. Deep and exhaustive modes also re-run the search with the corrected query.
`related_searches`	array	No	Related search suggestions
`topics`	array	No	Related topics

Type-specific arrays

Depending on the query intent, the response may include additional arrays alongside results:

Field	Present when
`videos`	Video intent queries
`images`	Image intent queries
`news`	News intent queries
`places`	Location/business queries
`profiles`	People-related queries
`social`	Social media queries
`academic`	Scholarly queries

Search results

Each result in the results array has this structure:

Field	Type	Always present	Description
`title`	string	Yes	Page title
`link`	string	Yes	Page URL (returned as `url` when `linkFormat=url`)
`desc`	string	Yes	Page description or summary
`source`	string	Yes	Domain name
`date`	string	No	Publication date
`snippet`	string	No	Query-relevant text excerpt (distinct from `desc`)
`answer`	string	No	Inline answer for instant answer results
`extracts`	array	No	Text extracts from the page (when `extracts=true`)

Fields added by `metadata=full`

These fields appear on results when you pass metadata=full. They are not included in the default metadata=basic response.

Field	Type	Description
`type`	string	Result type when classified (see result types)
`image`	string	Preview image URL
`contentType`	string	Schema.org content type (e.g., `Article`, `NewsArticle`)
`contentSafety`	object	Safety classification: `{rating, safeSearchApplied}` where `rating` is `"safe"`, `"unsafe"`, or `"unknown"`
`reader`	object	Extracted page content and metadata
`bang`	string	Bang shortcut for the result domain

Accessing key fields

data = response.json()

for result in data["results"]:
    # Always present
    print(result["title"], result["link"], result["source"])

    # Optional fields — check before accessing
    if result.get("snippet"):
        print(f"Snippet: {result['snippet']}")
    if result.get("extracts"):
        print(f"Extract: {result['extracts'][0][:200]}")
    if result.get("date"):
        print(f"Published: {result['date']}")

Result types

The type field indicates the kind of result:

Type	Description
`website`	Standard web page
`blog`	Blog post
`news`	News article
`video`	Video content
`image`	Image content
`place`	Business or place
`profile`	Person or entity profile
`social`	Social media content
`academic`	Scholarly or research content
`calculation`	Math computation result
`weather`	Weather data
`computation`	Computed answer
`instant answer`	Direct answer to a factual query

Instant answers

Some queries trigger instant answers alongside regular results.

Weather

Queries about weather return a weather object:

{
  "results_type": "Weather",
  "answer": "",
  "type": "Weather",
  "title": "Weather in San Francisco",
  "results": [],
  "weather": {
    "location": {
      "name": "San Francisco",
      "country": "US",
      "coordinates": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    },
    "temperature": 62,
    "feelsLike": 59,
    "units": "imperial",
    "description": "Partly Cloudy",
    "humidity": 72,
    "windSpeed": 12,
    "windDirection": 270,
    "pressure": 1013,
    "icon": "partly-cloudy",
    "cloudiness": 40,
    "visibility": 10000,
    "timestamp": "2025-03-15T14:00:00Z"
  },
  "metrics": {
    "query": "weather san francisco",
    "intent": "WeatherIntent",
    "timestamp": "2025-03-15T14:00:01Z",
    "duration": 850,
    "cost_dollars": 0.0018,
    "queries_executed": 1,
    "api_requests_count": 2,
    "results_returned": 0,
    "total_results_found": 0
  }
}

Use the units parameter to get results in metric or imperial. The default is auto-detected from the country parameter.

Calculation

Mathematical queries return a calculation object:

{
  "results_type": "Calculator",
  "answer": "",
  "type": "Calculator",
  "title": "150 * 1.08",
  "results": [],
  "calculation": {
    "expression": "150 * 1.08",
    "result": "162"
  },
  "metrics": { "..." : "..." }
}

Image results

Image queries return an images array with thumbnail and dimension data:

{
  "results_type": "Search",
  "answer": "",
  "type": "Search",
  "title": "Mountain landscape images",
  "results": [],
  "images": [
    {
      "title": "Mountain landscape",
      "link": "https://example.com/photo",
      "image": "https://example.com/photo.jpg",
      "source": "example.com",
      "type": "image",
      "thumbnail": "https://example.com/photo_thumb.jpg",
      "width": "1920",
      "height": "1080"
    }
  ],
  "metrics": { "..." : "..." }
}

Image results include thumbnail (thumbnail URL), width, and height as string values.

Parsing tips

Check results_type first to know the response shape before accessing type-specific fields
results is always an array but may be empty for instant answers (weather, calculations)
desc vs snippet: desc is the page’s general description; snippet is a query-relevant excerpt (when available)
answer at top level is a generated answer string (may be empty); answer on individual results is an inline answer for instant answer result types
Optional fields (date, image, snippet, extracts) may not be present on every result — always check before accessing

Search intents

The results_type and type fields reflect what kind of search was performed. You can force an intent with the intent parameter, or let the API auto-detect it. Common intent aliases:

Alias	Intent	Extra fields
`search`	General web search	—
`news`	News articles	`news`
`video`	Video content	`videos`
`images`	Image search	`images`
`weather`	Weather queries	`weather`
`calculate`	Math expressions	`calculation`
`wiki`	Wikipedia/knowledge	—
`code`	Programming queries	—
`recipe`	Recipe search	—
`place`	Business search	`places`
`time`	Time queries	—

See query parameters for the full list of intent aliases.

Metrics

The response always includes a metrics object with performance and billing data:

{
  "results": ["..."],
  "metrics": {
    "query": "quantum computing",
    "intent": "InstantAnswerIntent",
    "timestamp": "2026-07-15T01:29:20.468Z",
    "duration": 1713,
    "queries_executed": 1,
    "api_requests_count": 1,
    "results_returned": 3,
    "total_results_found": 71800116,
    "cost_dollars": 0.029886
  }
}

Field	Type	Description
`query`	string	The query as processed
`intent`	string	Detected or forced search intent
`timestamp`	string	Timestamp of the request
`duration`	number	Total request time in milliseconds
`cost_dollars`	number	Amount charged for this request in USD
`effort`	string	Resolved effort tier (`low`/`medium`/`high`/`max`). Present when `effort` was set, or when `searchMode` pins a fixed mode.
`queries_executed`	integer	Number of queries executed
`api_requests_count`	integer	Number of API requests made
`results_returned`	integer	Results returned in this response
`total_results_found`	integer	Total results found across sources
`cached`	boolean	Whether this response was served from cache. Only present on cache hits.
`cache_age_seconds`	integer	How old the cached response is, in seconds. Only present on cache hits.

Context format

With format=context, the API returns results as markdown with YAML frontmatter instead of JSON. This format is sized for LLM context windows and can be passed directly to a language model without JSON parsing.

curl "https://api.andiai.com/api/v1/search?q=climate+change+effects&format=context" \
  -H "x-api-key: YOUR_API_KEY"

Document-level frontmatter

The response starts with a YAML frontmatter block describing the search:

---
format: "andi-context/v1"
query: "climate change effects"
results_count: 10
timestamp: "2026-07-14T21:30:00Z"
search_mode: "auto"
cost_dollars: 0.0043
cached: false
response_time_ms: 1240
---

Field	Always present	Description
`format`	Yes	Always `"andi-context/v1"`
`query`	Yes	The search query
`results_count`	Yes	Number of results
`timestamp`	Yes	Request timestamp
`intent`	When available	Detected search intent
`results_type`	When available	Type of results
`corrected_query`	When available	Spell-corrected query
`related_searches`	When available	Related search suggestions
`topics`	When available	Related topics
`search_mode`	When available	The mode this request ran with. With the default `auto`, this shows the mode Andi selected for the query.
`effort`	When available	Resolved effort tier (`low`/`medium`/`high`/`max`), when `effort` was set or `search_mode` pins a fixed mode.
`cost_dollars`	When available	Amount charged in USD
`cached`	When available	Whether response was from cache
`cache_age_seconds`	When available	Cache age in seconds
`response_time_ms`	When available	Response time (omitted on cache hits)

Per-result structure

Each result renders as an <article> block with its own frontmatter:

<article source="example.com" rank="1">
---
title: "Climate Change Effects on Global Agriculture"
url: https://example.com/climate-agriculture
date: 2026-06-10
author: Dr. Sarah Chen
---

Climate change is altering growing seasons and precipitation patterns across
major agricultural regions...

<extracts>
Rising temperatures have shifted planting windows by 2-3 weeks in temperate
zones over the past decade.
</extracts>
</article>

A source line appears in the frontmatter only when the display source differs from the domain in the <article> tag. With metadata=full, each article’s frontmatter adds domain, publisher, type, content_type, lang, word_count, image, keywords, and summary when available.

Type-specific sections

The same type-specific groups the JSON response carries as additional arrays render as trailing sections after the main results, so a context-format caller sees everything a JSON caller would. Sections appear only when the group has results, in this order: Academic results, News results, Video results, Social results, Place results, Profile results. (images is JSON-only.) Each section is a markdown heading followed by a compact item list — title, url, and when available date, source, description, and duration for videos:

## News results

<news count="2">
- title: "Heat Records Fall Across Southern Europe"
  url: "https://example.com/heat-records"
  date: "2026-07-12"
  source: "example.com"
  desc: "Temperatures exceeded seasonal norms for a third consecutive week..."
</news>

Items already present in the main <article> results are not repeated in these sections.

Extracts in context format

extracts defaults to on for format=context (the opposite of JSON, where it defaults to off). To disable extracts in context format, pass extracts=false.

Next steps

Query parameters

Full parameter reference.

Content retrieval

Fetch full page content from any URL.

RAG pipeline

Use search results as LLM context.

Build with AI agents

MCP server and agent integration.

Getting started

Search

Features

Resources

Top-level fields

Type-specific arrays

Search results

Fields added by `metadata=full`

Accessing key fields

Result types

Instant answers

Weather

Calculation

Parsing tips

Search intents

Metrics

Context format

Document-level frontmatter

Per-result structure

Type-specific sections

Extracts in context format

Next steps

Query parameters

Content retrieval

RAG pipeline

Build with AI agents

​Top-level fields

​Type-specific arrays

​Search results

​Fields added by metadata=full

​Accessing key fields

​Result types

​Instant answers

​Weather

​Calculation

​Parsing tips

​Search intents

​Metrics

​Context format

​Document-level frontmatter

​Per-result structure

​Type-specific sections

​Extracts in context format

​Next steps

Query parameters

Content retrieval

RAG pipeline

Build with AI agents

Top-level fields

Type-specific arrays

Search results

Fields added by `metadata=full`

Accessing key fields

Result types

Instant answers

Weather

Calculation

Parsing tips

Search intents

Metrics

Context format

Document-level frontmatter

Per-result structure

Type-specific sections

Extracts in context format

Next steps