---
title: "Search Cities (v2)"
method: GET
path: "/api/v2/geo/search"
tags: ["Geo v2", "geo-v2"]
---

# Search Cities (v2)

`GET /api/v2/geo/search`

## Request

- Base URL: `https://api.freeastroapi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.freeastroapi.com/api/v2/geo/search`
- Auth: none declared

Search for cities by name prefix for autocomplete functionality.

**Authentication Required:**
- Requires a valid `x-api-key` header.

**Cost:**
- **Free Tier:** 1 Credit per request.
- **Paid Tiers (Entry, High):** 0 Credits (Unlimited).

Use it to help users select the correct city before making astrology calculations.

**Example usage:**
- `/api/v2/geo/search?q=par` → Returns Paris (FR), Paris (US), Paraná, etc.
- `/api/v2/geo/search?q=london&country=GB` → Returns only London, UK
- `/api/v2/geo/search?q=Jingzhou%2C%20Hubei` → Returns Jingzhou in Hubei, China
- `/api/v2/geo/search?q=Hubei%20Jingzhou` → Also returns Jingzhou in Hubei, China
- `/api/v2/geo/search?q=Jingzhou%20City%2C%20Hubei%20Province` → Accepts optional administrative suffixes

Results are sorted by population (largest cities first).

**Note:** This is the new v2 endpoint. The v1 endpoint (/api/v1/geo/search) 
remains free without API key until February 3, 2026, after which it will be deprecated.

## Query parameters

- `q` string, required: City name prefix with an optional state/province qualifier (e.g., 'Jingzhou, Hubei', 'Hubei Jingzhou', 'Jingzhou City, Hubei Province', or 'Jingzhou, Hubei, CN')
- `limit` integer: Maximum results to return (1-50)
- `country` string, nullable: Filter by ISO country code (e.g., 'US', 'FR')

## Response `200`

Successful Response

- CitySearchResponse: Response model for city search
  - `results` CityResult[], required
    - `name` string, required
    - `country` string, required
    - `state` string, nullable
    - `district` string, nullable
    - `lat` number, required
    - `lng` number, required
    - `timezone` string, required
    - `population` integer, required
  - `count` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/freeastroapi/apis/astroservice-api.md) · [All operations](https://skmtc.dev/freeastroapi/apis/astroservice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/freeastroapi/apis/astroservice-api/revisions/0c9b4a759522?raw)