searxng-mcp-go/docs/SEARXNG_RESPONSE_FIELDS.md
XLion 9617a6318f
test: consolidate answer contract ownership (#563)
* test: consolidate answer contract ownership

* test: address answer ownership review
2026-08-12 00:33:45 +08:00

352 lines
12 KiB
Markdown

# SearXNG JSON Response: `corrections` and `answers` Fields
Analysis of two optional fields in the SearXNG JSON search API response.
## Overview
SearXNG's JSON response (`GET /search?format=json`) returns these top-level fields:
```json
{
"query": "original query",
"number_of_results": 1234,
"results": [...],
"suggestions": ["suggested query 1", "suggested query 2"],
"answers": [...],
"corrections": ["corrected spelling 1", "corrected spelling 2"],
"infoboxes": [...],
"unresponsive_engines": [...]
}
```
`unresponsive_engines` is included only in debug output and contains `[engine_name, error_message]` pairs.
---
## `corrections`
### Definition
Spelling corrections detected by search engines for the user's query. Engines like
Google, Bing, or DuckDuckGo may identify typos and return corrected alternatives.
### Type
```
corrections: string[]
```
An array of strings. Each string is a corrected query variant.
### Source
- **Engine results**: When an engine detects a typo, it returns a result object with
a `"correction"` key. SearXNG collects these into a `set[str]` in `ResultContainer.corrections`.
- Duplicate corrections across engines are deduplicated (set semantics).
### When Non-Empty
- The user's query contains a likely misspelling.
- At least one selected engine provides spelling correction data.
- Common with Google, Bing, DuckDuckGo for typo queries.
### JSON Example
```json
{
"corrections": ["corrected query", "another correction"]
}
```
---
## `answers`
### Definition
Instant answers computed from the query. These are direct responses (not web links)
provided by SearXNG's built-in **answerers** and **plugins**.
### Type
```
answers: object[]
```
An array of typed answer objects. Each object's structure depends on the answer type.
### Common Answer Types
#### 1. `Answer` (union answer object)
The Go client represents all answer types as a single `Answer` struct with
optional typed fields. Legacy string answers populate the `answer` field;
typed answers (translations, weather) use template-specific fields.
```json
{
"answer": "The computed result or information",
"engine": "engine_name",
"template": "template_name",
"url": "https://example.com/result",
"translations": [
{
"text": "translated text",
"transliteration": "transliteration",
"examples": ["example 1", "example 2"],
"definitions": ["definition 1"],
"synonyms": ["synonym 1"]
}
],
"current": {
"location": { "name": "Tokyo", "country_code": "JP" },
"summary": "Partly cloudy",
"temperature": { "val": 22.5, "unit": "°C" },
"condition": "partly_cloudy"
},
"forecasts": [...],
"service": "engine_service_name"
}
```
Fields:
- `answer` (string): Legacy answer text. Typed answers may omit this field; a
fallback string is derived by the normalization layer.
- `engine` (string): The engine that produced the answer.
- `template` (string, optional): The engine's answer template name.
- `url` (string, optional): A URL associated with the answer.
- `translations` (array, optional): Translation entries, present for translation-type answers.
- `current` (object, optional): Current weather conditions, present for weather-type answers.
- `forecasts` (array, optional): Weather forecast entries, present for weather-type answers.
- `service` (string, optional): Service name or category for the answer.
#### 2. `Translations` (translation results)
A translation-type answer contains one or more `TranslationItem` entries
with the translated text, transliteration, examples, definitions, and synonyms.
The Go struct for each translation entry:
```json
{
"text": "translated text",
"transliteration": "transliteration",
"examples": ["example 1", "example 2"],
"definitions": ["definition 1"],
"synonyms": ["synonym 1"]
}
```
```go
type TranslationItem struct {
Text string `json:"text"`
Transliteration string `json:"transliteration,omitempty"`
Examples []string `json:"examples,omitempty"`
Definitions []string `json:"definitions,omitempty"`
Synonyms []string `json:"synonyms,omitempty"`
}
```
Fields:
- `text` (string): The translated text.
- `transliteration` (string, optional): Transliteration of the translated text.
- `examples` (array of strings, optional): Usage examples for the translation.
- `definitions` (array of strings, optional): Definitions of the translated term.
- `synonyms` (array of strings, optional): Synonyms for the translated term.
**Fallback display:** When the legacy `answer` string is empty and `Translations` is populated, the canonical answer fallback logic produces `"Translation: <text>; <text>; ..."` during response normalization.
#### 3. `WeatherAnswer` (weather data)
A weather-type answer contains a `Current` weather observation and/or
`Forecasts` array, each represented as a `WeatherItem`.
The Go struct for a weather observation:
```json
{
"location": {
"name": "Tokyo",
"latitude": 35.6762,
"longitude": 139.6503,
"elevation": 40.0,
"country_code": "JP",
"timezone": "Asia/Tokyo"
},
"datetime": "2026-05-28T12:00:00+09:00",
"summary": "Partly cloudy",
"temperature": { "val": 22.5, "unit": "°C" },
"feels_like": { "val": 21.0, "unit": "°C" },
"condition": "partly_cloudy",
"pressure": { "val": 1013.25, "unit": "hPa" },
"humidity": { "val": 65.0, "unit": "%" },
"wind_from": { "val": 180.0, "unit": "°" },
"wind_speed": { "val": 3.5, "unit": "m/s" },
"cloud_cover": 40
}
```
```go
type WeatherItem struct {
Location WeatherLocation `json:"location"`
Datetime *string `json:"datetime,omitempty"`
Summary string `json:"summary,omitempty"`
Temperature WeatherMeasure `json:"temperature"`
FeelsLike *WeatherMeasure `json:"feels_like,omitempty"`
Condition string `json:"condition"`
Pressure *WeatherMeasure `json:"pressure,omitempty"`
Humidity *WeatherMeasure `json:"humidity,omitempty"`
WindFrom *WeatherMeasure `json:"wind_from,omitempty"`
WindSpeed *WeatherMeasure `json:"wind_speed,omitempty"`
CloudCover *int `json:"cloud_cover,omitempty"`
}
```
Supporting types:
```go
type WeatherLocation struct {
Name string `json:"name"`
Latitude float64 `json:"latitude,omitempty"`
Longitude float64 `json:"longitude,omitempty"`
Elevation float64 `json:"elevation,omitempty"`
CountryCode string `json:"country_code,omitempty"`
Timezone string `json:"timezone,omitempty"`
}
type WeatherMeasure struct {
Val float64 `json:"val"`
Unit string `json:"unit,omitempty"`
}
```
Fields (WeatherItem):
- `location` (object): Location information (name, coordinates, country, timezone).
- `datetime` (string, optional): ISO 8601 timestamp for the observation.
- `summary` (string, optional): Human-readable weather summary.
- `temperature` (object): Temperature measurement with value and unit.
- `feels_like` (object, optional): Apparent (feels-like) temperature.
- `condition` (string): Weather condition code (e.g., "partly_cloudy", "clear", "rain").
- `pressure` (object, optional): Atmospheric pressure measurement.
- `humidity` (object, optional): Relative humidity percentage.
- `wind_from` (object, optional): Wind direction in degrees.
- `wind_speed` (object, optional): Wind speed measurement.
- `cloud_cover` (integer, optional): Cloud cover percentage.
**Fallback display:** When the legacy `answer` string is empty and `Current` is populated, the canonical answer fallback logic produces a human-readable summary during response normalization, preferring `Current.Summary` first, then falling back to `"Weather: <location>, <temperature>, <condition>"`.
The `WeatherMeasure.String()` method returns a compact representation: `"<value> <unit>"` or just `"<value>"` when unit is empty.
### Answer Types Summary
| Template | Typed Fields | Fallback Derivation |
|----------|-------------|---------------------|
| `simple` or empty | None (uses legacy `answer` string) | N/A — `answer` already populated |
| `translations.html` | `Translations []TranslationItem` | `"Translation: <text>; <text>; ..."` |
| `weather.html` | `Current *WeatherItem`, `Forecasts []WeatherItem` | `Current.Summary` or `"Weather: <location>, <temperature>, <condition>"` |
### Source
1. **Answerers** (`searx.answerers`): Registered modules that pattern-match the query
and return instant answers. Built-in answerers include:
- **Random**: `random number`, `random string`, `random sha256`
- **Statistics**: `10 + 5`, `sqrt(144)`, unit conversions
2. **Plugins** (`searx.plugins`): Plugins with `post_search` hooks can inject
answers into the result container.
### Processing Flow
```
Query received
-> answerers.ask(query) called first
-> If match: answer(s) added to AnswerSet, skip engine search
-> If no answerer match: standard engine search proceeds
-> plugins post_search hooks run on results
-> Can inject additional answers
```
Key detail: If an answerer matches the query, SearXNG returns the answer
**without** performing a standard engine search (the `search_answerers` short-circuits
`search_standard`).
### When Non-Empty
- Query matches a built-in answerer pattern (e.g., `random sha256`, `10 usd to eur`).
- A plugin's `post_search` hook produces an answer.
- An engine returns a legacy `{"answer": "..."}` result (deprecated).
### Deduplication
Answers are deduplicated by hash. The `AnswerSet` class ignores duplicates before
sorting and iteration.
### JSON Example
```json
{
"answers": [
{"answer": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}
]
}
```
---
## Key Differences: `corrections` vs `answers`
| Aspect | `corrections` | `answers` |
|--------|---------------|-----------|
| **Purpose** | Suggest query fixes | Provide direct answers |
| **Type** | `string[]` | `object[]` (typed) |
| **Content** | Corrected spellings | Computed/instant results |
| **Source** | Search engines | Answerers + plugins |
| **Effect on search** | None (suggestion only) | May skip engine search |
| **Typical use** | "Did you mean X?" | Calculations, facts, translations |
---
## Current Implementation Note
The `searxng-mcp-go` codebase now exposes `answers`, `infoboxes`, and
`unresponsive_engines` in the `SearchResponse` struct. The Go struct maps:
```go
type Answer struct {
Answer string `json:"answer"`
Engine string `json:"engine"`
Template string `json:"template,omitempty"`
URL string `json:"url,omitempty"`
Translations []TranslationItem `json:"translations,omitempty"`
Current *WeatherItem `json:"current,omitempty"`
Forecasts []WeatherItem `json:"forecasts,omitempty"`
Service string `json:"service,omitempty"`
}
type SearchResponse struct {
Query string `json:"query"`
Warning string `json:"warning"`
Answers []Answer `json:"answers,omitempty"`
NumberOfResults int `json:"number_of_results"`
Infoboxes []Infobox `json:"infoboxes,omitempty"`
Results []SearchResult `json:"results"`
Suggestions []string `json:"suggestions"`
UnresponsiveEngines [][]string `json:"unresponsive_engines,omitempty"`
Debug bool `json:"-"`
}
```
Note: `corrections` is **not** currently exposed. `unresponsive_engines` is
omitted unless debug mode is enabled. DuckDuckGo answers that overlap with
infobox content are deduplicated by `DeduplicateAnswers` before the response
is returned.
---
## References
- Source: `searx/results.py` — `ResultContainer` class
- Source: `searx/webutils.py` — `get_json_response()` function
- Source: `searx/answerers/` — Built-in answerer modules
- Source: `searx/result_types/answer.py` — Answer type definitions
- Source: `searx/search/__init__.py` — `search_answerers()` method