# SKILL.md

---

# Ubient Go(TM) Search API Skill

> name: ubient-go-search
> description: A web search skill that uses the Ubient Go(TM) metasearch engine API. Use this skill when the user requests web searches, news searches, image searches, or the latest information. No authentication is required. Receives JSON responses via HTTP GET/POST requests.
> author: Ubient
> version: “1.0”
> homepage: [https://go.ubient.dscloud.biz](https://go.ubient.dscloud.biz)
> documentation: [https://ubient.dscloud.biz/docs/service/go-search/](https://ubient.dscloud.biz/docs/service/go-search/)

## 1. Overview

Ubient Go(TM) is a privacy-focused metasearch engine designed for AI agents.
It aggregates results from multiple search engines and returns them as a unified JSON response.
No authentication is required.

- **Authentication**: Not required (no API key)
- **Protocol**: HTTP GET or POST
- **Response Format**: JSON (`format=json` must be specified)

## 2. Endpoints

### 2.1 Search Endpoint

```
GET  https://go.ubient.dscloud.biz/search
POST https://go.ubient.dscloud.biz/search
```

Both GET and POST use the same search endpoint.
POST can be used when search parameters should be sent in the request body instead of appearing in the URL.

### 2.2 Configuration Endpoint

```
GET https://go.ubient.dscloud.biz/config
```

Returns instance configuration: available categories, engine list, language settings, and other publicly available configuration information.
Does not return search results.

## 3. Request Parameters

### 3.1 `q` (Required)

Specifies the keyword or search query to be processed.

| Property | Value |
| --- | --- |
| Parameter | `q` |
| Type | String |
| Required | **Yes** |
| Description | The query to use for the search |

Search terms containing Korean characters, spaces, special characters, or reserved URL characters must be properly URL-encoded.
When making requests from the command line, the `--data-urlencode` option provided by `curl` can encode search terms automatically.

**Example**: `q=대한민국`

### 3.2 `format` (Required for AI agents)

Specifies the output format of the response.

| Property | Value |
| --- | --- |
| Parameter | `format` |
| Type | String |
| JSON Value | `json` |
| Required | **Yes** for AI agent usage |

**WARNING**: If `format=json` is not specified, an HTML response will be returned.
AI agents must always include `format=json`.

### 3.3 `categories` (Optional)

Specifies the search categories to use. Multiple categories can be specified using comma (`,`) separator.

| Property | Value |
| --- | --- |
| Parameter | `categories` |
| Type | String |
| Value Separator | Comma (`,`) |
| Required | No |

Available categories may vary depending on the service configuration.
The categories currently provided by the instance can be retrieved through the `/config` endpoint.

**Examples**:

- `categories=general`
- `categories=general,news`

### 3.4 `language` (Optional)

Specifies the language code to use for the search.

| Property | Value |
| --- | --- |
| Parameter | `language` |
| Type | String |
| Required | No |

**Examples**: `language=ko`, `language=en`, `language=ja`

### 3.5 `pageno` (Optional)

Specifies the page number of results.

| Property | Value |
| --- | --- |
| Parameter | `pageno` |
| Type | Integer |
| Required | No |
| Default | `1` |

### 3.6 `time_range` (Optional)

Specifies the time range to apply to search results.

| Value | Description |
| --- | --- |
| `day` | The past day |
| `month` | The past month |
| `year` | The past year |

This parameter is applied to search engines that support the specified time filter.
Not all search engines support the same time-range filters.

### 3.7 `safesearch` (Optional)

Specifies the SafeSearch filtering level to apply to search results.

| Value | Description |
| --- | --- |
| `0` | No filtering |
| `1` | Moderate filtering |
| `2` | Strict filtering |

## 4. Request Examples

### 4.1 Basic Search (curl, Bash)

```
curl -sS -G "https://go.ubient.dscloud.biz/search" \
  --data-urlencode "q=대한민국" \
  --data-urlencode "format=json"
```

### 4.2 Windows PowerShell

```
curl.exe -sS -G "https://go.ubient.dscloud.biz/search" --data-urlencode "q=대한민국" --data-urlencode "format=json"
```

### 4.3 Multiple Parameters

```
curl -sS -G "https://go.ubient.dscloud.biz/search" \
  --data-urlencode "q=python programming" \
  --data-urlencode "format=json" \
  --data-urlencode "categories=general" \
  --data-urlencode "language=en" \
  --data-urlencode "pageno=1"
```

### 4.4 Direct URL (HTTP tools or fetch)

```
GET https://go.ubient.dscloud.biz/search?q=%EB%8C%80%ED%95%9C%EB%AF%BC%EA%B5%AD&format=json&categories=general&language=ko
```

## 5. JSON Response Structure

### 5.1 Top-Level Fields

| Field | Type | Description |
| --- | --- | --- |
| `query` | String | The processed search query |
| `results` | Array | A list of search results (see 5.3) |
| `answers` | Array | Answer-style results |
| `corrections` | Array | Search query correction information |
| `infoboxes` | Array | Summary information and related attributes, as objects (see 5.4) |
| `suggestions` | Array | Suggested related search terms |
| `unresponsive_engines` | Array | List of engines that failed to respond (see 5.5) |

### 5.2 Empty Results Response

An HTTP request can succeed even when the `results` array is empty.

```
{
  "query": "example query",
  "results": [],
  "answers": [],
  "corrections": [],
  "infoboxes": [],
  "suggestions": [],
  "unresponsive_engines": []
}
```

### 5.3 Search Result Entries (`results[]`)

| Field | Type | Description |
| --- | --- | --- |
| `title` | String | The title of the search result |
| `url` | String | The original URL of the search result |
| `content` | String | A description or excerpt of the result. It can be an empty string. |
| `engine` | String | The name of one search engine that provided the result. If several engines returned the same URL, all of them are listed in `engines`. |
| `engines` | Array | The names of all search engines that returned the result |
| `positions` | Array | The rank at which the result appeared in the contributing engines’ result lists |
| `category` | String | The category of the search result |
| `score` | Number | A ranking score calculated from `positions`. Higher values rank higher. Not normalized to 0-1 range; values from about 0.05 to about 2.29 were observed. Compare scores only within the same response. |
| `publishedDate` | String/null | Publication date if available |
| `img_src` | String | Image source URL (for image results) |
| `thumbnail` | String | Thumbnail URL |
| `parsed_url` | Array | URL parsed into components |
| `template` | String | Template identifier |

**Important Notes**:

- Entries in the same response do not necessarily contain the same set of keys.
- Missing values appear in different forms: an omitted field, `null`, or an empty string (`""`).
- Clients should not assume that every result contains the same set of fields, and should treat an empty string and `null` the same way when checking for a missing value.

### 5.4 Infobox Entries (`infoboxes[]`)

Infobox entries contain generic fields such as `url`, `template`, `parsed_url`, `title`, `thumbnail`, `priority`, `engines`, `positions`, `score`, `category`, `publishedDate`, and `iframe_src`.

### 5.5 Unresponsive Engine Entries (`unresponsive_engines[]`)

Each entry is a two-element array: `[engine, reason]`

| Position | Type | Description |
| --- | --- | --- |
| `0` | String | The name of the search engine |
| `1` | String | A human-readable reason |

```
"unresponsive_engines": [
  ["brave", "너무 많은 요청"],
  ["duckduckgo", "CAPTCHA"]
]
```

- The reason text is translated and can carry a translated “Suspended” prefix.
- Do not match on the exact text of the reason; use it for logging and display.
- The response can still contain results when `unresponsive_engines` is not empty.

## 6. HTTP Responses and Error Handling

| Status Code | Meaning | Recommended Action |
| --- | --- | --- |
| `200 OK` | The HTTP request was processed successfully | Inspect the response body and parse the JSON. |
| `403 Forbidden` | Access to the requested resource or output format was denied | Check the requested output format and the server’s access policies. |
| Other status codes | An error occurred during request processing, on the server, or in the network | Inspect the HTTP status code and response body. |

**Note**: `200 OK` indicates that the HTTP request was processed successfully. It does not guarantee that the `results` array contains one or more entries.

When a `403 Forbidden` response is returned, check the HTTP status code before attempting to parse the response body as JSON.

### Recommended Processing Sequence

1. Send the HTTP request.
2. Check the HTTP status code.
3. If the request succeeds, parse the response body as JSON.
4. Validate the presence and data types of fields, including `results`.
5. Process the results according to further decision-making.

## 7. Configuration Retrieval (`/config`)

### Request URL

```
GET https://go.ubient.dscloud.biz/config
```

### Main Response Fields

| Field | Description |
| --- | --- |
| `instance_name` | The name of the search instance |
| `categories` | The list of available search categories |
| `engines` | Search engine configuration information |
| `locales` | Language information available for the interface |
| `autocomplete` | The autocomplete provider configuration |
| `safe_search` | The default SafeSearch setting |

### Engine Entry Fields (`engines[]`)

| Field | Type | Description |
| --- | --- | --- |
| `name` | String | The name of the search engine |
| `categories` | Array | The categories the engine belongs to |
| `shortcut` | String | The short name of the engine |
| `enabled` | Boolean | Whether the engine is enabled. Disabled engines are also listed. |
| `paging` | Boolean | Whether the engine supports paging (`pageno`) |
| `language_support` | Boolean | Whether the engine supports a language parameter |

The `/config` endpoint provides instance information; it does not return search results.

## 8. Usage Considerations

- Search terms containing Korean characters or spaces must be URL-encoded.
- Different search engines may return different fields in their results. Always check for field existence.
- Monitor `unresponsive_engines` to understand the search engine response status.
- A `200 OK` response does not guarantee non-empty results; always check the `results` array.
- When receiving `403 Forbidden`, check the HTTP status code before attempting JSON parsing.
- The `score` field is not normalized to 0-1 range. Use it only for relative comparison within the same response.

## 9. AI Agent Instructions

1. **Always include `format=json`** in every request.
2. **URL-encode** search terms properly.
3. Extract `url`, `title`, `content` fields from the `results` array and present them to the user.
4. If `suggestions` array contains related search terms, inform the user.
5. If `answers` array contains direct answers, display them with priority.
6. If `infoboxes` array contains summary information, use it as rich context.
7. Check `unresponsive_engines` and inform the user if most engines are unresponsive.
8. **Check the HTTP status code first** before attempting to parse JSON.