# How search finds cities

This page tells why a city ranks first, why a text finds no city, and how to match a list of city names from a file.

## Names

Autocomplete and search find a city by each of its names, in all languages, and by its historic names. Names in other scripts, such as `Москва` or `東京`, find the city directly. Search does not convert them to Latin letters.

The match ignores case, accents, and punctuation, so `sao paulo` finds São Paulo. A `St` at the start of a name is equal to `Saint`.

A result always shows the current name in the requested language, also if the text matched a historic name.

## Autocomplete or search

[Autocomplete](/docs/api#autocompleteCities) is for a text that a person types. It returns cities with a name that starts with the text.

[Search](/docs/api#searchCities) is for a full name, such as a name from a file or a form. It tries these matches in this order, and stops at the first match that finds cities:

1. The exact name.
2. The name without a word such as `City`.
3. A name that starts with the text.
4. A name with one typo.

Both routes return no cities for a text of fewer than 2 characters. Both accept a name with one typo only for a text of 4 or more characters.

## Country and region after a comma

In search, the text after the last comma selects the country or the region. `Burlington, Vermont` returns the city in Vermont. The text after the comma can be a country name, a country code, or a region name.

If the text is the name of a region or a country, search applies a strict rule. Search returns only a city with this name that is a capital, the seat of a region, or a city of 500,000 or more people. `California` returns no city, and not California, Maryland. This rule does not apply if the request gives a region.

## Ranking

The rank of a city uses the quality of the match, the population, and the place type. Autocomplete also uses the number of names of the city in other languages. The main name of a city is its English name or its name in the source data. Each other name is an alias.

- A large city with a name that starts with the text ranks above a small city with the exact name.
- A large city with the exact text as a name in another language ranks above a small city with the exact text as its main name.
- A capital ranks higher, and a district ranks lower.
- A city on a list of well-known cities ranks higher.

## The match field

Each result of autocomplete and search has `match`:

| Value    | Meaning                                                                       |
| -------- | ----------------------------------------------------------------------------- |
| `exact`  | The text is the main name of the city.                                        |
| `alias`  | The text is a different name of the city, such as a name in another language. |
| `prefix` | A name of the city starts with the text.                                      |
| `fuzzy`  | A name of the city has one typo, compared with the text.                      |

## Match city names from a file

To find the ID of each city in a file, such as a CSV export of customers, send each name to Search:

1. Add the region or the country after a comma, such as `Springfield, Illinois` or `Porto, PT`. If the file has a country column, send it in the `country` parameter.
2. Accept the first result only if its `match` is `exact` or `alias`, and no other result has `exact` or `alias`.
3. Put each other row in a list for a person to check.

A `prefix` or `fuzzy` match is a guess. Two exact matches mean that the name is not unique: `Springfield` with no region gives many cities with the exact name.