Search cities by name

# Search cities by name

Searches cities by name or country codes — returns up to 100 cities per page
Upstream direct: USD 0.0/call.
Overflow: USD 0.0/call via orthogonal.
Disabled draft retail: maximum of published direct/overflow fixed prices, without markup. Unknown overflow is not a zero quote. Draft retail USD 0.0/billable call.
Usage limits: Free city dictionary. Pages start at 1. A metropolitan area may have several city IDs; select the IDs appropriate to your search.
Supplier limits: 500 requests/minute per IP globally; per-user route limits scale with plan (60/min Starter, 120/min Pro, 600/min Scale). Autocomplete/lookup routes use a separate per-user bucket.
Catalog prices and provider response fields are not proof of actual TREG charges. Reconcile X-Treg-Cost-Micro with call IDs and usage records; caching and overflow may change the charge.
Before enabling, verify business results and charges for this account, plus X-Treg-Meta customer tagging and usage-by-tag reconciliation. Testnet verification results for this definition are recorded below.
Testnet verification (2026-11-04): business result passed; OpenAny debit USD 0 matched the configured retail policy for this request. This is one observed call, not a guarantee for future requests. The paired example is captured from testnet; long excerpts may be shortened. Actual TREG upstream debit was not verified.
Documentation: https://openany.si/apis/9da37119-7779-402f-9b00-c2228ed33b4e
Method: POST
Endpoint: https://api.openany.si/v1/agent-apis/treg/call/companyenrich.geo.cities.search
Price: $0 / call
Provider: treg
Contract revision: 1
Price source: selected implementation in the OpenAny public API catalog. Price update time: not supplied.

Use OPENANY_API_KEY from the environment. API Key calls use your shared balance.

## Prepared request
```bash
curl \
  'https://api.openany.si/v1/agent-apis/treg/call/companyenrich.geo.cities.search' \
  -X POST \
  -H "Authorization: Bearer $OPENANY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "countryCodes": [
    "US"
  ],
  "query": "san fran"
}'
```

## API contract
```json
{
  "resource_type": "api",
  "name": "Search cities by name",
  "endpoint": "https://api.openany.si/v1/agent-apis/treg/call/companyenrich.geo.cities.search",
  "method": "POST",
  "content_type": "application/json",
  "execution_mode": "sync",
  "authentication": {
    "type": "bearer",
    "environment_variable": "OPENANY_API_KEY"
  },
  "inputs": [
    {
      "description": "JSON request body for Search cities by name. See individual field descriptions for input requirements.",
      "json_schema": {
        "additionalProperties": false,
        "description": "JSON request body for Search cities by name. See individual field descriptions for input requirements.",
        "properties": {
          "countryCodes": {
            "description": "ISO alpha-2 codes to scope the search",
            "example": [
              "US"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "page": {
            "description": "1-based page number",
            "minimum": 1,
            "type": "integer"
          },
          "query": {
            "description": "city name; prefixes work ('san fran' matched three San Francisco entries)",
            "example": "san fran",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [],
        "type": "object"
      },
      "location": "body",
      "name": "body",
      "nullable": false,
      "pointer": "",
      "required": true,
      "type": "object"
    }
  ],
  "billing": {
    "currency": "USD",
    "mode": "fixed",
    "priceMicroUsd": "0",
    "rounding": null,
    "unit": "call",
    "unitQuantity": null
  },
  "examples": [
    {
      "http_status": 200,
      "name": "Third-party reference · Testnet verified: business + billing",
      "request": {
        "body": {
          "countryCodes": [
            "US"
          ],
          "query": "san fran"
        },
        "headers": {},
        "path": {},
        "query": {}
      },
      "response_body": {
        "items": [
          {
            "id": 130518,
            "latitude": 37.77823,
            "longitude": -122.4425,
            "name": "City and County of San Francisco"
          },
          {
            "id": 131186,
            "latitude": 37.77493,
            "longitude": -122.41942,
            "name": "San Francisco"
          },
          {
            "id": 131281,
            "latitude": 37.65466,
            "longitude": -122.40775,
            "name": "South San Francisco"
          }
        ],
        "page": 1,
        "totalItems": 3,
        "totalPages": 1
      }
    }
  ]
}
```