---

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
documentation: 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.