API Guide

Overview

Ubient Go Search is a private search service within Ubient Private Cloud Infrastructure (UPCI™). It aims to avoid practices such as search history retention and advertising tracking, providing a free search solution that is friendly to AI agents through an API endpoint that supports JSON.

The Ubient Go Search API is a search interface that accepts search queries through HTTP requests and returns search results in JSON format.

External applications and scripts can use the API to retrieve search results and process the returned data programmatically.

Basic Information

Property	Description
Service Name	Ubient Go Search
Base URL	https://go.ubient.dscloud.biz
Search Endpoint	/search
Supported HTTP Methods	GET, POST
Response Format Covered in This Guide	JSON
Request Encoding	UTF-8 search terms and URL encoding
API Authentication	The examples in this guide do not use a separate authentication header.

Endpoint

The complete URL for the search API is:

https://go.ubient.dscloud.biz/search

Search requests can be sent using either the GET or POST HTTP method.

• GET: Passes search parameters through the URL query string.
• POST: Passes search parameters in a request body using the application/x-www-form-urlencoded content type.

Request Parameters

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

Example:

q=대한민국

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.

format

Specifies the output format of the response.

Property	Value
Parameter	format
Type	String
JSON Value	json
Description	Returns search results in JSON format

To process the API response programmatically, specify:

format=json

The examples in this guide use JSON responses verified on the current service.

CSV and RSS output are not documented as supported formats because HTTP 403 responses have been observed when requesting these formats from the current service.

categories

Specifies the search categories to use.

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

Example:

categories=general

Multiple categories can also be specified.

categories=general,news

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

language

Specifies the language code to use for the search.

Property	Value
Parameter	language
Type	String
Required	No

Example:

language=en

If this parameter is omitted, the instance’s default search settings apply.

Select language codes according to the languages supported by the service.

pageno

Specifies the page number of the search results.

Property	Value
Parameter	pageno
Type	Integer
Default	1
Required	No

Example:

pageno=2

Page numbering starts at 1. The number of pages available depends on the search engines and instance configuration.

time_range

Specifies the time range to apply to search results.

Value	Description
day	The past day
month	The past month
year	The past year

Example:

time_range=month

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

safesearch

Specifies the SafeSearch filtering level to apply to search results.

Value	Description
0	No filtering
1	Moderate filtering
2	Strict filtering

Example:

safesearch=1

This filter is applied to search engines that support the setting.

If the parameter is omitted, the instance’s default setting applies.

---

GET Requests

GET requests pass search parameters through the URL query string.

Basic Request

The following URL requests a search for test and specifies JSON as the response format.

https://go.ubient.dscloud.biz/search?q=test&format=json

Use the following command to make the request from a command line:

Bashcurl -sS "https://go.ubient.dscloud.biz/search?q=test&format=json"

Searching with Korean Terms

URL encoding is recommended for search terms containing Korean characters or spaces.

On Linux, macOS, or systems with a compatible curl executable, use the following command:

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

In Windows PowerShell, use curl.exe:

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

The -G option adds the parameters specified with --data-urlencode to the URL query string and sends a GET request.

Specifying Multiple Search Parameters

Search terms, categories, languages, and page numbers can be specified together.

Bashcurl -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"

Each parameter can be specified independently. Optional parameters only need to be included when required.

---

POST Requests

POST requests pass search parameters in the HTTP request body.

The request body uses the application/x-www-form-urlencoded format.

Basic Request

Bashcurl -sS -X POST "https://go.ubient.dscloud.biz/search" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "q=test" \
  --data-urlencode "format=json"

In Windows PowerShell, use the following command:

PowerShellcurl.exe -sS -X POST "https://go.ubient.dscloud.biz/search" -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "q=test" --data-urlencode "format=json"

Characteristics of POST Requests

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.

However, using POST does not, by itself, provide additional anonymity or confidentiality for search requests. When search terms contain personal or sensitive information, the request and the service’s data-handling policies should also be considered.

---

JSON Response Structure

When a request specifies format=json, the search API returns a JSON response.

The response may contain the search query, search results, related information, and the response status of individual search engines.

Main 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.5)
suggestions	Array	Suggested related search terms
unresponsive_engines	Array	Search engines that did not respond or returned an error, as [engine, reason] pairs (see 5.6)

The contents and number of entries in these fields may vary depending on the search query, search engine responses, and instance configuration.

Example Response

The following example is an excerpt from a real response to q=test. Two of the 20 returned results are shown, and the content values are shortened with …. Actual response contents vary between requests.

JSON{
  "query": "test",
  "results": [
    {
      "url": "https://en.wikipedia.org/wiki/Test",
      "title": "Test - Wikipedia",
      "content": "Other uses in science and technology · …",
      "engine": "wikipedia",
      "template": "default.html",
      "parsed_url": ["https", "en.wikipedia.org", "/wiki/Test", "", "", ""],
      "img_src": "",
      "thumbnail": "",
      "priority": "",
      "engines": ["google cse", "wikipedia"],
      "positions": [1, 7],
      "score": 2.2857142857142856,
      "category": "general",
      "publishedDate": null,
      "iframe_src": null
    },
    {
      "template": "default.html",
      "title": "Fast.com: Internet Speed Test",
      "content": "What is FAST.com measuring? …",
      "img_src": "",
      "iframe_src": "",
      "audio_src": "",
      "thumbnail": "",
      "publishedDate": null,
      "pubdate": "",
      "length": null,
      "views": "",
      "author": "",
      "metadata": "",
      "priority": "",
      "engines": ["google cse"],
      "open_group": false,
      "close_group": false,
      "positions": [3],
      "score": 0.3333333333333333,
      "category": "general",
      "url": "https://fast.com/",
      "engine": "google cse",
      "parsed_url": ["https", "fast.com", "/", "", "", ""]
    }
  ],
  "answers": [],
  "corrections": [],
  "infoboxes": [
    {
      "infobox": "Test",
      "id": "https://www.wikidata.org/entity/Q37315170",
      "content": "family name",
      "img_src": null,
      "urls": [
        { "title": "Wikidata", "url": "http://www.wikidata.org/entity/Q37315170" }
      ],
      "attributes": [
        { "label": "Writing system", "value": "Latin script", "entity": "P282" }
      ],
      "engine": "wikidata",
      "url": null,
      "template": "default.html",
      "parsed_url": null,
      "title": "",
      "thumbnail": "",
      "priority": "",
      "engines": ["wikidata"],
      "positions": "",
      "score": 0,
      "category": "",
      "publishedDate": null,
      "iframe_src": null
    }
  ],
  "suggestions": [],
  "unresponsive_engines": [
    ["brave", "너무 많은 요청"],
    ["duckduckgo", "CAPTCHA"]
  ]
}

Search Result Entries

Each entry in the results array may contain the following information.

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. It is not normalized to the range 0–1: values from about 0.05 to about 2.29 were observed, and a result returned by several engines can exceed 1. Compare scores only within the same response.
template	String	The template identifier of the result type (observed: default.html)
parsed_url	Array	The url split into six components: scheme, host, path, parameters, query, and fragment, in that order
img_src	String	An image URL. Observed as an empty string in every result of the verified response.
thumbnail	String	A thumbnail URL, or an empty string
priority	String	Result priority. Observed as an empty string.
publishedDate	Null or string	Observed as null in every result of the verified response
iframe_src	Null or string	Observed as null or an empty string

The following fields were present only in some results.

Field	Observed value
audio_src	Empty string
pubdate	Empty string
length	null
views	Empty string
author	Empty string
metadata	Empty string
open_group	false
close_group	false

Entries in the same response do not necessarily contain the same set of keys. In the verified response, the first result (returned by two engines) did not contain audio_src, pubdate, length, views, author, metadata, open_group, or close_group, while single-engine results did.

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.

When No Search Results Are Returned

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

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

In this situation, distinguish between successful HTTP and JSON response processing and the actual availability of search results.

The unresponsive_engines array contains the engines that did not respond or encountered errors during the search, together with a reason (see 5.6).

Infobox Entries

Each entry in the infoboxes array is an object.

Field	Type	Description
infobox	String	The title of the infobox. Use this field rather than title.
id	String	The identifier of the described entity
content	String	A short description
img_src	Null or string	An image URL
urls	Array	Related links, as objects with title and url
attributes	Array	Attribute list, as objects with label, value, and entity
engine	String	The search engine that provided the infobox

Infobox entries also contain generic fields such as url, template, parsed_url, title, thumbnail, priority, engines, positions, score, category, publishedDate, and iframe_src. In the verified response these carried empty or null values (title was an empty string and parsed_url was null).

Unresponsive Engine Entries

Each entry in the unresponsive_engines array is a two-element array: [engine, reason].

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

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

The reason text is translated, and it can carry a translated “Suspended” prefix. In the verified response the text was Korean (너무 많은 요청, meaning “too many requests”) or CAPTCHA. 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.

---

Using the API with Python

The API can be called and its JSON response processed using only the Python standard library.

The following example submits a Korean search query and prints the title and URL of each returned result.

Pythonimport json
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import urlopen

BASE_URL = "https://go.ubient.dscloud.biz"

params = {
    "q": "대한민국",
    "format": "json",
    "pageno": 1,
}

url = f"{BASE_URL}/search?{urlencode(params)}"

try:
    with urlopen(url, timeout=20) as response:
        data = json.load(response)

except HTTPError as error:
    print(f"HTTP error: {error.code} {error.reason}")
    raise

except URLError as error:
    print(f"Network error: {error.reason}")
    raise

print("Query:", data.get("query", ""))
print("Number of results:", len(data.get("results", [])))

for index, result in enumerate(data.get("results", []), start=1):
    title = result.get("title") or "(Untitled)"
    result_url = result.get("url") or ""

    print(f"{index}. {title}")
    print(f"   {result_url}")

Code Explanation

1. The params dictionary specifies the search query and response format.
2. urlencode() encodes the URL query parameters.
3. urlopen() sends a GET request to the search API.
4. json.load() converts the response into a JSON object.
5. The code iterates over the results array and prints each result’s title and URL.
6. HTTP errors and network errors are handled separately.

This example can process a response containing an empty results array without raising an error, provided that the response contains the expected JSON structure.

In production applications, it is recommended to implement request timeouts, error handling, result-field validation, and request-frequency management.

---

Retrieving Service Configuration

Ubient Go Search provides instance configuration information in JSON format through the /config endpoint.

Request URL

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

Example Request

Bashcurl -sS "https://go.ubient.dscloud.biz/config"

Windows PowerShell:

PowerShellcurl.exe -sS "https://go.ubient.dscloud.biz/config"

The response may contain the service name, search categories, search engine information, language settings, and other publicly available configuration information.

The main fields include the following.

Field	Description
instance_name	The name of the search instance
categories	The list of available search categories
engines	Search engine configuration information (see below)
locales	Language information available for the interface
autocomplete	The autocomplete provider configuration
safe_search	The default SafeSearch setting

Each entry in engines contains the following fields.

Field	Type	Description
name	String	The name of the search engine. It matches the names used in engine and engines in search results.
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
languages	Array	Language codes supported by the engine
regions	Array	Region codes supported by the engine
safesearch	Boolean	Whether the engine supports the SafeSearch filter (see 2.7)
time_range_support	Boolean	Whether the engine supports the time-range filter (see 2.6)
timeout	Number	The request timeout configured for the engine

This information may change depending on the instance configuration.

If an application needs to determine the currently available categories or search engine information, it can retrieve the current configuration from this endpoint rather than relying on a hard-coded list. Check enabled to see which engines are active, and safesearch and time_range_support to see which engines apply the filters described in 2.6 and 2.7.

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

---

HTTP Responses and Error Handling

API clients should inspect both the HTTP status code and the response body.

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.

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. Distinguish between an empty search result and a failed HTTP request.
6. If unresponsive_engines contains entries, process the associated status information separately.

---

Usage Considerations

Search Parameter Encoding

Search terms containing Korean characters, spaces, or special characters should be URL-encoded. When constructing URLs manually, missing or incorrect encoding may cause search terms to be transmitted differently from what was intended.

Differences Between Search Engines

The number of results, titles, descriptions, and available fields may vary depending on the search engine and result type. Applications should not assume that every search request returns the same number of results or an identical data structure.

Search Engine Response Status

The unresponsive_engines field provides status information that can be examined separately from the main search results. The API may return a JSON response even when some search engines do not respond. In one verified response to q=test, results were returned while two engines that /config lists as enabled (brave and duckduckgo) were reported in unresponsive_engines. In that case, the results come from fewer engines than the number of enabled engines.

Request and Error Handling

Applications that call the API repeatedly should implement appropriate timeouts and error handling. Avoid unlimited retry loops, and comply with the service’s usage policies and access restrictions.

Response Field Compatibility

Applications should select the fields they need based on actual responses and handle cases in which optional fields are missing, set to null, or set to an empty string.