# API Guide - Link: https://ubient.dscloud.biz/docs/service/go-search/go-search-api/ - Published: 2026-10-12T22:00:37+09:00 - Author: Ubient ## 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: ```ubient-docs-code 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: ```ubient-docs-code 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: ```ubient-docs-code 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: ```ubient-docs-code categories=general ``` Multiple categories can also be specified. ```ubient-docs-code 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: ```ubient-docs-code 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: ```ubient-docs-code 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: ```ubient-docs-code 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: ```ubient-docs-code 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. ```ubient-docs-code https://go.ubient.dscloud.biz/search?q=test&format=json ``` Use the following command to make the request from a command line: ```ubient-docs-code 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: ```ubient-docs-code Bashcurl -sS -G "https://go.ubient.dscloud.biz/search" \ --data-urlencode "q=대한민국" \ --data-urlencode "format=json" ``` In Windows PowerShell, use `curl.exe`: ```ubient-docs-code 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. ```ubient-docs-code 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 ```ubient-docs-code 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: ```ubient-docs-code 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. ```ubient-docs-code 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. ```ubient-docs-code 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]`. ```ubient-docs-code 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. ```ubient-docs-code 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 ```ubient-docs-code https://go.ubient.dscloud.biz/config ``` ### Example Request ```ubient-docs-code Bashcurl -sS "https://go.ubient.dscloud.biz/config" ``` Windows PowerShell: ```ubient-docs-code 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.