> ## Documentation Index
> Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Autocomplete

> Type-ahead search for cities, states, and countries with deterministic ranking and ready-to-display labels

Search cities, states, and countries for a type-ahead / autocomplete UI. Unlike [Fuzzy Search](/api/endpoints/fuzzy-search) — which ranks purely by trigram similarity — autocomplete uses a stricter, deterministic order built for a dropdown: **exact matches first, then starts-with matches, then the closest remaining fuzzy matches**, with population and then record ID breaking any ties. The same query always returns the same order. Each result also carries a ready-to-display `label` (e.g. `"Mumbai, Maharashtra, India"`) so you don't have to assemble one yourself.

<Note>**Availability:** Supporter, Professional, and Business plans. Returns `403` on Community, Starter, and Legacy plans. [Compare plans](https://countrystatecity.in/pricing?source=playground\&campaign=autocomplete_api), or see **Trying it without a paid plan** below.</Note>

<Info>Matching checks the English name, native name, and stored translations. Translation matching starts at 3 characters. Responses are cached separately by query, filters, plan, locale, and translation output.</Info>

## Response

Returns an array. Each item carries the standard fields for the entity (`city`, `state`, or `country`) at your plan's data-access level, plus:

<Note>
  City results always include `country_code` and `state_code`, regardless of your plan's data-access level — even the basic-tier field set includes them here, since you can't build a useful `label` or scope a follow-up request without them. (States already include `country_code` at every tier under the normal field rules, so no such exception is needed there.)
</Note>

## Ranking

Results are ordered deterministically — the same query always returns the same order:

| Priority | Rule |
| - | - |
| 1 | Exact match (case-insensitive) on `name` or `native` |
| 2 | Starts-with match on `name` or `native` |
| 3 | Closest remaining fuzzy match, by `match_score` |
| 4 | Larger `population` breaks ties within the same rank |
| 5 | Lower `id` breaks any remaining tie |

<RequestExample>
  ```bash cURL (typo) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/search/autocomplete?q=Mumbay&type=city&country=IN' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```bash cURL (state, scoped to a country) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/search/autocomplete?q=Maharashtra&type=state&country=IN' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```bash cURL (city, scoped to a state) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/search/autocomplete?q=Pune&type=city&country=IN&state=MH&limit=5' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ q: 'Mumbay', type: 'city', country: 'IN' });
  const response = await fetch(
    `https://api.countrystatecity.in/v1/search/autocomplete?${params}`,
    { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
  );

  const results = await response.json();
  results.forEach((r) => console.log(`${r.label} (${r.match_score})`));
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    'https://api.countrystatecity.in/v1/search/autocomplete',
    params={'q': 'Mumbay', 'type': 'city', 'country': 'IN'},
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
  )

  for result in response.json():
      print(f"{result['label']} -> {result['match_score']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - City typo match (Supporter, Professional, Business) theme={null}
  [
    {
      "id": 132332,
      "name": "Mumbai",
      "state_id": 4008,
      "state_code": "MH",
      "country_id": 101,
      "country_code": "IN",
      "latitude": "19.07283000",
      "longitude": "72.88261000",
      "timezone": "Asia/Kolkata",
      "native": "मुंबई",
      "type": "city",
      "label": "Mumbai, Maharashtra, India",
      "match_score": 0.75,
      "matched_field": "name"
    }
  ]
  ```

  ```json 200 - State match theme={null}
  [
    {
      "id": 4008,
      "name": "Maharashtra",
      "iso2": "MH",
      "country_id": 101,
      "country_code": "IN",
      "latitude": "19.75147980",
      "longitude": "75.71388840",
      "timezone": "Asia/Kolkata",
      "type": "state",
      "label": "Maharashtra, India",
      "match_score": 1,
      "matched_field": "name"
    }
  ]
  ```

  ```json 400 - Query too short theme={null}
  {
    "status": "error",
    "message": "Invalid query parameters: q: Search query must be at least 2 characters"
  }
  ```

  ```json 400 - state without country theme={null}
  {
    "status": "error",
    "message": "Invalid query parameters: state: country is required when filtering by state"
  }
  ```

  ```json 400 - state with a non-city type theme={null}
  {
    "status": "error",
    "message": "Invalid query parameters: state: state is only a valid filter when type=city"
  }
  ```

  ```json 403 - Feature Restricted theme={null}
  {
    "status": "error",
    "message": "This feature is not available on your current plan.",
    "details": {
      "feature": "autocomplete",
      "currentTier": "starter",
      "requiredTier": "supporter",
      "upgradeUrl": "https://app.countrystatecity.in/pricing"
    }
  }
  ```
</ResponseExample>

## Trying it without a paid plan

A separate **Playground** plan powers the interactive API documentation — a basic-tier field set on a shared rate limit sized for many concurrent visitors, not a per-visitor quota. It isn't something you can sign up for directly; it is only for the docs playground. For your own integration, [choose a Supporter plan or higher](https://countrystatecity.in/pricing?source=playground\&campaign=autocomplete_api).

## Related Endpoints

* [Fuzzy Search](/api/endpoints/fuzzy-search) — pure similarity ranking, without the tiered exact/starts-with/fuzzy order or a computed `label`
* [Get All Countries](/api/endpoints/get-all-countries) — exact/substring inline search via `?q=`
* [Get Cities by Country](/api/endpoints/get-cities-by-country) — list cities, filterable by `?q=`


## OpenAPI

````yaml GET /search/autocomplete
openapi: 3.0.3
info:
  title: Country State City API
  description: >-
    Geographic data API providing countries, states, cities, timezones,
    currencies, and phone dial codes with tiered access levels.


    ## Authentication

    All endpoints require an API key passed via the `X-CSCAPI-KEY` header. Get
    your free key at [app.countrystatecity.in](https://app.countrystatecity.in).


    ## Pricing & Limits

    The fields returned, endpoints available, and request quotas depend on your
    plan. See current tiers and limits at:


    **[countrystatecity.in/pricing](https://countrystatecity.in/pricing)**


    ## Data Access Levels

    Each plan includes a data access level that controls which fields are
    returned:


    - **Basic** — Core fields: id, name, iso2, iso3, phonecode, capital,
    currency, coordinates, region, timezones, emoji

    - **Coordinates** — Basic + extended metadata (population, tld, nationality,
    currency details, postal codes, etc.)

    - **Full** — All fields including translations (18+ languages) and
    wikiDataId


    Fields restricted to higher tiers are marked in each schema below.


    ## Feature Gating

    Some endpoints require a minimum tier. Restricted endpoints return `403`
    with an `upgradeUrl` when accessed on a lower plan. Check the [pricing
    page](https://countrystatecity.in/pricing) for current feature availability.


    ## Rate Limiting

    Requests exceeding your daily or monthly quota receive a `429` response with
    your current limit, period, tier, and an upgrade URL.


    ## Caching

    Cacheable geographic responses include `Cache-Control`, `ETag`, and
    `X-Cache` (HIT/MISS) headers; send `If-None-Match` on them to receive `304
    Not Modified`. Phone number parsing is never cached (`Cache-Control:
    no-store`, no `ETag`); see each endpoint for exceptions.


    ## Usage Headers

    All `/v1/*` responses include usage and plan headers:

    - `X-CSC-Plan` — your current tier

    - `X-CSC-Daily-Used` / `X-CSC-Daily-Limit` — today's usage vs limit

    - `X-CSC-Monthly-Used` / `X-CSC-Monthly-Limit` — this month's usage vs limit


    Use these to monitor consumption without a separate API call.
  contact:
    name: Darshan Gada (dr5hn)
    email: gadadarshan@gmail.com
    url: https://countrystatecity.in
  license:
    name: Creative Commons Attribution 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: 2.4.1
servers:
  - url: https://api.countrystatecity.in/v1
    description: Production API
security: []
tags:
  - name: Countries
    description: Country data — 250+ countries with metadata, coordinates, and translations
  - name: States
    description: State/province/region data — 5,000+ subdivisions
  - name: Cities
    description: City data — 150,000+ cities worldwide
  - name: Postcodes
    description: >-
      Postcode and ZIP code lookup and search. Informational data, not address
      verification.
  - name: Regions
    description: Geographic regions and subregions — continental groupings of countries
  - name: Timezones
    description: >-
      IANA timezone lookup by country, state, or city — includes UTC offset and
      DST status
  - name: Currencies
    description: ISO 4217 currency data — list all currencies or look up by country
  - name: Phone
    description: >-
      International dial codes — list, lookup by country, and E.164 phone number
      parsing
  - name: ISO
    description: >-
      ISO 3166 code lookup and conversion — country (alpha-2/3/numeric) and
      state (ISO 3166-2)
  - name: Search
    description: Typo-tolerant fuzzy search across cities, states, and countries
  - name: Changes
    description: >-
      Data change feed — track additions, removals, and updates to place records
      over time. **Professional and Business plans only.**
  - name: Meta
    description: Information about the dataset release currently served
paths:
  /search/autocomplete:
    get:
      tags:
        - Search
      summary: Location autocomplete
      description: >-
        As-you-type search for cities, states, or countries. It searches English
        and native names, plus translations for queries of at least 3
        characters. Results rank exact matches first, then starts-with, then
        fuzzy matches. Each result includes a ready-to-display `label`; when
        `locale` is set, that label starts with the localized name.


        Example: `?q=ムンバイ&type=city&locale=ja` finds Mumbai and returns a
        Japanese label while preserving the English `name` and stable `id`.


        **Availability:** Supporter+ plans for production use; other plans can
        try basic autocomplete in the public playground. [Compare
        plans](https://countrystatecity.in/pricing?source=api_playground&campaign=localized_autocomplete).
      operationId: autocompleteSearch
      parameters:
        - name: q
          in: query
          description: Search query — 2 to 100 characters. Case-insensitive.
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 100
            example: Mumbay
        - name: type
          in: query
          description: Entity type to search
          required: false
          schema:
            type: string
            enum:
              - city
              - state
              - country
            default: city
            example: city
        - name: country
          in: query
          description: >-
            ISO 3166-1 alpha-2 country code to narrow the search (e.g., `IN`).
            Invalid when `type=country` — supplying both returns a `400`.
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 2
            pattern: ^[A-Za-z]{2}$
            example: IN
        - name: state
          in: query
          description: >-
            State/province ISO code to narrow a city search further (e.g.,
            `MH`). State codes are not globally unique, so this requires
            `country` to also be set and is valid only when `type=city`.
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 20
            example: MH
        - name: limit
          in: query
          description: Maximum number of results to return (1–50)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
            example: 10
        - name: locale
          in: query
          description: >-
            Adds `localized_name` and `matched_locale`, and starts `label` with
            the localized name. The English `name` and `id` stay unchanged.
            **Supporter+ plans only.**
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 7
            pattern: ^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$
            example: ja
        - name: include_translations
          in: query
          description: >-
            When `true`, includes the full translation JSON string. **Supporter+
            plans only.**
          required: false
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: List of matching results ranked by relevance
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
            ETag:
              $ref: '#/components/headers/ETag'
            X-Cache:
              $ref: '#/components/headers/XCache'
            X-CSC-Plan:
              $ref: '#/components/headers/XCSCPlan'
            X-CSC-Daily-Used:
              $ref: '#/components/headers/XCSCDailyUsed'
            X-CSC-Daily-Limit:
              $ref: '#/components/headers/XCSCDailyLimit'
            X-CSC-Monthly-Used:
              $ref: '#/components/headers/XCSCMonthlyUsed'
            X-CSC-Monthly-Limit:
              $ref: '#/components/headers/XCSCMonthlyLimit'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AutocompleteResult'
        '400':
          description: >-
            Missing or invalid query parameter, `state` used without `country`
            or with a non-city type, or `country` supplied together with
            `type=country`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Feature not available on your current plan. Requires Supporter+.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureError'
              example:
                status: error
                message: This feature is not available on your current plan.
                details:
                  feature: autocomplete
                  currentTier: starter
                  requiredTier: supporter
                  upgradeUrl: https://countrystatecity.in/pricing
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - ApiKeyAuth: []
components:
  headers:
    CacheControl:
      description: Cache directive
      schema:
        type: string
        example: public, max-age=3600
    ETag:
      description: Entity tag for conditional requests (use with `If-None-Match`)
      schema:
        type: string
        example: '"a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5"'
    XCache:
      description: Whether the response was served from cache
      schema:
        type: string
        enum:
          - HIT
          - MISS
        example: HIT
    XCSCPlan:
      description: Your current pricing tier
      schema:
        type: string
        enum:
          - community
          - starter
          - supporter
          - professional
          - business
          - legacy
          - custom
        example: supporter
    XCSCDailyUsed:
      description: Number of requests used today
      schema:
        type: integer
        example: 42
    XCSCDailyLimit:
      description: Your daily request limit (or 'unlimited' for custom plans)
      schema:
        type: string
        example: '1000'
    XCSCMonthlyUsed:
      description: Number of requests used this month
      schema:
        type: integer
        example: 850
    XCSCMonthlyLimit:
      description: Your monthly request limit (or 'unlimited' for custom plans)
      schema:
        type: string
        example: '30000'
  schemas:
    AutocompleteResult:
      type: object
      description: >-
        A single result from a location autocomplete query, ranked by relevance
        (exact match, then starts-with, then fuzzy). Field set depends on
        `type`. Note: unlike most other city fields, `country_code` and
        `state_code` on city results are always returned regardless of plan
        tier, since the client needs them to disambiguate the `label`.
      properties:
        type:
          type: string
          enum:
            - country
            - state
            - city
          description: Entity type of the matched result
          example: city
        label:
          type: string
          description: >-
            Ready-to-display label. When `locale` is supplied on a Supporter+
            plan, the first place name is localized. Parent state and country
            names remain English.
          example: ムンバイ, Maharashtra, India
        id:
          type: integer
          format: int64
          description: Entity ID (city, state, or country)
          example: 57606
        name:
          type: string
          description: English name of the matched entity
          example: Mumbai
        translations:
          type: string
          nullable: true
          description: >-
            JSON string of translations. **Supporter+ plans only, and only when
            `include_translations=true` is passed.**
        localized_name:
          type: string
          nullable: true
          description: >-
            Localized display name selected by `locale`. The English `name`
            remains unchanged. **Supporter+ plans only.**
          example: ムンバイ
        matched_locale:
          type: string
          nullable: true
          description: >-
            Translation or fallback used for `localized_name`: the exact locale,
            base language, `native`, or `en`. **Supporter+ plans only.**
          example: ja
        iso2:
          type: string
          nullable: true
          description: >-
            ISO 3166-1 alpha-2 code (`type=country`) or state ISO code
            (`type=state`). Not present on `type=city` results.
          example: IN
        iso3:
          type: string
          nullable: true
          description: >-
            ISO 3166-1 alpha-3 code. Only present for `type=country`; not
            present otherwise.
          example: IND
        state_code:
          type: string
          nullable: true
          description: >-
            Parent state ISO code. Always present for `type=city`; `null`
            otherwise.
          example: MH
        country_code:
          type: string
          nullable: true
          description: >-
            Parent country ISO2 code. Always present for `type=city` and
            `type=state`; `null` for `type=country`.
          example: IN
        match_score:
          type: number
          description: >-
            Relevance score (0–1, rounded to 2 decimals). Higher is a closer
            match.
          example: 0.95
        matched_field:
          type: string
          enum:
            - name
            - native
            - translation
          description: Which field the match was found against.
          example: translation
      required:
        - type
        - label
        - id
        - name
        - match_score
        - matched_field
    StatusError:
      type: object
      description: Error envelope used by the postcode and meta endpoints.
      properties:
        status:
          type: string
          example: error
        message:
          type: string
        details:
          type: object
          nullable: true
          properties:
            reason:
              type: string
              description: >-
                Machine-readable reason. Check this instead of parsing
                `message`.
          additionalProperties: true
      required:
        - status
        - message
    FeatureError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
          example: This feature is not available on your current plan.
        details:
          type: object
          properties:
            feature:
              type: string
              description: The feature flag that was denied
              example: bulkStates
            currentTier:
              type: string
              example: community
            requiredTier:
              type: string
              nullable: true
              description: >-
                Lowest plan that unlocks the feature; null when it cannot be
                determined
              example: starter
            upgradeUrl:
              type: string
              format: uri
              example: https://countrystatecity.in/pricing
          required:
            - feature
            - currentTier
            - requiredTier
            - upgradeUrl
      required:
        - status
        - message
        - details
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: >-
            Daily usage limit exceeded. Please try again tomorrow or contact
            support for higher limits.
        limit:
          type: integer
          description: Your plan's limit for the exceeded period
          example: 100
        period:
          type: string
          enum:
            - daily
            - monthly
          example: daily
        tier:
          type: string
          description: Your current tier
          example: community
        upgradeUrl:
          type: string
          description: URL to upgrade your plan
          example: https://countrystatecity.in/pricing
      required:
        - error
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized. You shouldn't be here.
    RateLimited:
      description: Daily or monthly usage limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: >-
              Daily usage limit exceeded. Please try again tomorrow or contact
              support for higher limits.
            limit: 100
            period: daily
            tier: community
            upgradeUrl: https://countrystatecity.in/pricing
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: >-
        API key for authentication. Get your free key at
        [app.countrystatecity.in](https://app.countrystatecity.in).
      name: X-CSCAPI-KEY
      in: header

````

## Related topics

- [Get Cities by Country](/api/endpoints/get-cities-by-country.md)
- [CLI](/api/sdks/cli.md)
- [Localized Place Names](/api/localization.md)
- [Nearby Search](/api/endpoints/get-search-nearby.md)
- [Fuzzy Search](/api/endpoints/fuzzy-search.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.