Introduction

Welcome to the Cmds Search API Documentation! Here, you'll find information on how to use all components of the Search API and other Cmds services.

(Nearly) all API routes start with /api. All responses have a success boolean in the returned JSON, unless otherwise shown. There may be an error string returned when success is false. Success and error alone don't determine request status; check the HTTP status code for details (see Handling Errors).

Rate Limits

Each user gets a limited number of free requests per IP per bucket. A bucket is a group of related endpoints that share the same limit. Limits reset over time, starting at the first request until the next reset time. If a limit has been exceeded, the Retry-After header shows when the next retry is allowed. Repeat violations may trigger longer secondary cooldowns.

Each route has its own rate limit defined as x requests per x time. Example: search → 30 requests per 60 seconds.

Handling Errors

Almost all failed requests return a JSON object with success: false and an error field describing what went wrong.

Additionally, HTTP status codes are used to indicate the type of error:

400 Bad Request - Missing or invalid parameters.
403 Forbidden - Access denied for this resource.
404 Not Found - Endpoint or resource does not exist.
429 Too Many Requests - Rate limit exceeded. Check the Retry-After header.
500 Internal Server Error - Unexpected server error.

Example error response:

{
  "success": false,
  "error": "Missing required parameters"
}

Search API

Endpoints for searching web results and fetching supported bangs.

/api/search

Performs a search and returns structured results.

Bucket: search - 30 requests / 60 seconds

Parameters

Parameter	Description	Default
`?q`	Search query*	Required*
`?qt`	Query type	`all`
`?page`	Page number	`1`
`?ss`	SafeSearch enabled	`1`
`?lang`	Language (auto, en, jp, etc.)	`auto`
`?kb`	Knowledge box toggle	`0`

Example Response

{
  "success": True,
  "page": 1,
  "total_pages": 25,
  "query": "test",
  "query_type": "all",
  "show_explicit": false,
  "results": [
    {
      "description": "",
      "favicon": "https://en.wikipedia.org/static/favicon/wikipedia.ico",
      "json_ld": "[...]",
      "snippet": "<b>George</b> <b>Washington</b> (February 22, 1732 [O.S. February 11, 1731] \u2013 December 14, 1799) was a Founding Father and the first president of the United States, serving from 1789 to 1797. As commander of the Continental\u2026",
      "text": "George Washington (February 22, 1732 [O.S. February 11, 1731] \u2013 December 14, 1799) was a Founding Father and the first president of the United States, serving from 1789 to 1797. As commander of the Continental Army\u2026",
      "title": "George Washington - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/george_washington"
    }
    ...
  ],
}

Search result field values may be null if it's a generated field, or an empty string '' if it's a page data field.

Knowledge Box


"knowledge_box": {
    "caption": "Portrait, c. 1803",
    "images": [
      "https://upload.wikimedia.org/wikipedia/commons/thumb/b/b6/Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg/500px-Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg",
      "https://upload.wikimedia.org/wikipedia/commons/thumb/2/2e/George_Washington_signature.svg/330px-George_Washington_signature.svg.png"
    ],
    "infobox": {
      "Born": "February 22, 1732 Popes Creek, Virginia, British America",
      "Died": "December 14, 1799 (1799-12-14) (aged 67) Mount Vernon, Virginia, U.S.",
      "Occupation": "Military officer, politician, surveyor, planter",
      "Spouse": "Martha Dandridge Custis (m. 1759)",
      "Vice President": "John Adams"
    },
    "link": "https://en.wikipedia.org/wiki/George_Washington",
    "summary": "George Washington was a Founding Father and the first president of the United States, serving from 1789 to 1797.",
    "title": "George Washington"
}

The context of the query may push relevant infobox information towards the top of the infobox pairs.

/api/bangs

Returns the list of supported search bangs.

Example Response

{
  "!g": {"url": "https://www.google.com/search?q={}", "site": "Google"},
  "!ddg": {"url": "https://duckduckgo.com/?q={}", "site": "DuckDuckGo"}
}

/verify-bot

A supplimentary route that allows you to check if an IP address belongs to Cmds Search.

Bucket: verify-bot — 15 requests / 30 seconds

Parameter	Description	Default
`?ip`	IP address to check	Request origin's IP

Example Responses

{
  "verified": false,
  "bot": null,
  "ip": "8.8.8.8",
  "note": "Unverified or non-Cmds crawler"
}

{
  "verified": true,
  "bot": "cmdsearchbot",
  "ip": "12.34.56.789",
  "note": "Verified Cmds Search crawler"
}

Geolocation API

Endpoints for retrieving IP location and client details.

/api/geo

Returns location data for an IP. Uses the origin's IP if none is provided.

Bucket: geo — 10 requests / 20 seconds

Parameters

Parameter	Description	Default
`?ip`	IP address to lookup	Request origin's IP

Example Response

{
  "success": true,
  "accuracy": 1000,
  "asn": 15169,
  "asn_org": "GOOGLE",
  "city": null,
  "continent": "North America",
  "continent_code": "NA",
  "country": "United States",
  "country_iso": "US",
  "ip": "8.8.8.8",
  "latitude": 37.751,
  "longitude": -97.822,
  "postal": null,
  "region": null,
  "region_iso": null,
  "timezone": "America/Chicago"
}

/api/client

Returns client IP, geolocation, browser, OS, and device info.

Bucket: geo — 10 requests / 20 seconds

Parameters

Parameter	Description	Required
`?ip`	Client IP address	No
`?ua`	User-Agent string	*If `?ip=` was specified. Defaults to request origin

Example Response

{
  "success": true,
  "accuracy": 5,
  "asn": 15169,
  "asn_org": "GOOGLE",
  "city": "Mountain View",
  "continent": "North America",
  "continent_code": "NA",
  "country": "United States",
  "country_iso": "US",
  "device_type": "Desktop",
  "ip": "8.8.8.8",
  "latitude": 37.4056,
  "longitude": -122.0775,
  "postal": "94043",
  "region": "California",
  "region_iso": "CA",
  "timezone": "America/Los_Angeles",
  "browser": {
    "name": "Chrome",
    "version": "141.0.0"
  },
  "device": {
    "brand": null,
    "model": null
  },
  "os": {
    "name": "Windows",
    "version": "10"
  }
}

Dictionary API

Fetch word definitions, examples, and synonyms.

/api/define

Gets word definitions from the internal dictionary.

Bucket: define — 30 requests / 60 seconds

Parameter	Description	Required
`?word`	Word to define	Yes*

Example Response

{
  "success": true,
  "word": "try"
  "definitions": [
      "definition": "test the limits of",
      "examples": [
        "You are trying my patience!"
      ],
      "part_of_speech": "verb",
      "synonyms": [
        "try",
        "strain",
        "stress"
      ]
    },
    {
      "definition": "give pain or trouble to",
      "examples": [
        "I've been sorely tried by these students"
      ],
      "part_of_speech": "verb",
      "synonyms": [
        "try"
      ]
    },
    ...
  ],
}

Translation API

Endpoints for translating text between languages. This API is hosted on translate.cmds.media, not search.cmds.media.

Domain: translate.cmds.media

/api/translate

Translates text from one language to another using Cmds Translate.

Bucket: translate — 20 requests / 60 seconds

Request Body

Send as application/json.

{
    "text": "Hello world",
    "source": "en",
    "target": "fr"
}

Or, Use URL query parameters:

translate.cmds.media/api/translate?text=Hello%20World&source=en&target=fr

Field	Description	Required
`text`	Text to translate	Yes*
`source`	Source language code (use `auto` for auto-detect)	No
`target`	Target language code	Yes*

Example Response

{
    "success": true,
    "source": "auto",
    "detected_source": "en",
    "target": "fr",
    "input": "Hello",
    "translation": "Bonjour"
}

Notes

This endpoint is available only on translate.cmds.media.
Automatic source detection uses probability based on frequency and syntax.
Text must be below 5120 characters.
Supports common language codes (ISO 639-1), you can get a list with Supported Languages.

/api/translate/bulk

Translates multiple texts at once in a single request.

Bucket: translate — 20 requests / 60 seconds

Request Body

Send as application/json.

{
  "texts": ["Hello world", "How are you?"],
  "source": "auto",
  "target": "fr"
}

Field	Description	Required
`texts`	List of texts to translate	Yes*
`source`	Source language code (`auto` to auto-detect)	No
`target`	Target language code	Yes*

Example Response

{
  "success": true,
  "source": "auto",
  "detected_source": "en",
  "target": "fr",
  "input": ["Hello world", "How are you?"],
  "translations": ["Bonjour le monde", "Comment ça va ?"]
}

Notes

Maximum items per request: 16.
Each text must be below 5120 characters.
If source is set to auto, the most common detected language among the texts is used.

/api/romanize

Converts text from certain languages into their romanized (Latin script) form.

Bucket: romanize — 20 requests / 60 seconds

Request Body / Query Parameters

Send as application/json or form data. Use URL query parameters.

{
    "text": "こんにちは",
    "source": "ja"
}

Field	Description	Required
`text`	Text to romanize	Yes*
`source`	Source language code (use `auto` for auto-detect). Natively Supported: `ja, zh, ko, ru`	No

Example Response

{
    "success": true
    "detected_lang": "ko",
    "input": "\uc88b\uc544\uc694\uc640 \uad6c\ub3c5\uc744 \uc78a\uc9c0 \ub9c8\uc138\uc694",
    "romanized": "joh-a-yo-wa gudog-eul ij-ji mase-yo",
}

Notes

If source is set to auto or not provided, the language is automatically detected.

/api/languages

Returns a list of all languages supported by Cmds Translate.

Example Response

{
    "success": true,
    "languages": {
        "af": "Afrikaans",
        "ar": "Arabic",
        "bg": "Bulgarian",
        ...
    }
}

cCaptcha

cCaptcha is Cmds' Captcha system for telling bots and humans apart.