# search_locations (/docs/mcp/tools/search-locations)

{/* Generated by scripts/sync-mcp-tools.mjs from happierleads-api. Do not edit: change src/routes/mcp/toolDocs.json there, or add content/mcp-notes/search_locations.mdx. */}

**Search locations** · Read-only

Looks up location names as the location filters expect them: every country with city data, US states (optionally matching q) or cities matching q (optionally within one country). Use it before filtering leads or prospects by a city or state. Free.

| Connection | Account URL, team member URL or OAuth |
| --- | --- |

## Parameters [#parameters]

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | `string` | Yes | Website ID from list_websites. |
| `kind` | `"countries" \| "states" \| "cities"` | Yes | countries, states (US) or cities. |
| `q` | `string` | No | Part of the name to search for (needed for cities). |
| `country` | `string` | No | Cities only: limit to one country. |
| `limit` | `number` | No | Cities only: how many to return (1-100). |

## Tool definition [#tool-definition]

What your assistant receives from `tools/list`:

```json
{
  "name": "search_locations",
  "title": "Search locations",
  "annotations": {
    "title": "Search locations",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "websiteId": {
        "type": "string",
        "description": "Website ID from list_websites."
      },
      "kind": {
        "type": "string",
        "enum": [
          "countries",
          "states",
          "cities"
        ],
        "description": "countries, states (US) or cities."
      },
      "q": {
        "type": "string",
        "description": "Part of the name to search for (needed for cities)."
      },
      "country": {
        "type": "string",
        "description": "Cities only: limit to one country."
      },
      "limit": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "description": "Cities only: how many to return (1-100)."
      }
    },
    "required": [
      "websiteId",
      "kind"
    ]
  }
}
```