How to Get the Right Place When Names Repeat

A user types a place name that exists many times, such as Springfield, which is the name of cities in Illinois, Massachusetts, Missouri, Ohio, Oregon, and other US states. The Geoapify Forward Geocoding API returns the best matches for the name, but not necessarily the one the user means.

Tell the API where to look. Use a bias to rank places near the user or the map first without excluding others, or a filter to return only places inside the map view or your service area. Combine both to search an area and rank the results inside it.

Task flow: repeated place name + user location, map view, or service area → Forward Geocoding with bias and filter → the intended place first.

Choose a filter or a bias

Without a filter or a bias, the API returns the best matches for the name. This request asks for cities named Springfield:

https://api.geoapify.com/v1/geocode/search?text=Springfield&type=city&limit=5&format=json&apiKey=YOUR_API_KEY

It returned five cities with the same confidence, 1: Springfield in Illinois, Massachusetts, Missouri, Ohio, and Oregon. Each one is a correct match for the text, so the API can't tell which one the user means.

The default bias. When a request has no bias, the API uses countrycode:auto: it detects a country from the IP address of the request and ranks places in that country first. Users in different countries can therefore see a different first result for the same text. Set bias=countrycode:none to turn this off.

Choose by what your application knows about the user:

filter excludes places outside the area; bias only changes the order. When a wrong result in another area is worse than no result, use a filter. When the user may really mean a distant place, use a bias.

You can combine several filters of different types, separated by |: a place must match all of them. Several biases of different types are also separated by |: places matching any of them are ranked first. You can send a filter and a bias in the same request; see Combine a filter and a bias.

Other details for repeated names:

• Result type. type=city limits the results to cities, so streets or businesses named Springfield don't appear. Other values include postcode, street, and amenity; see the Forward Geocoding parameters.
• More results. limit is the maximum number of results, not a guaranteed count.
• Show the state. Several results can have the same name. Show formatted or the state_code so the user can see which one is which.
• Coordinates. Values in proximity, rect, and circle are ordered as longitude, latitude.

Prefer places near the user

A user in Boston searches for Springfield. Pass the user's location as a proximity bias and ask for the nearest match:

https://api.geoapify.com/v1/geocode/search?text=Springfield&type=city&bias=proximity:-71.0589,42.3601&limit=1&format=json&apiKey=YOUR_API_KEY

Reduced response:

{
  "results": [
    {
      "formatted": "Springfield, MA, United States of America",
      "city": "Springfield",
      "county": "Hampden County",
      "state": "Massachusetts",
      "state_code": "MA",
      "country_code": "us",
      "lon": -72.5886727,
      "lat": 42.1018764,
      "result_type": "city",
      "distance": 129180.83201719406,
      "rank": { "confidence": 1 }
    }
  ]
}

The nearest Springfield is in Massachusetts, 129 km from Boston (distance is in metres). Without the bias, Springfield, Illinois came first.

The location can come from the browser's Geolocation API, the IP Geolocation API, or a place the user saved. An approximate, city-level location is enough to rank places by distance. See How to Pre-fill Country, Phone Code and Currency from the Visitor's IP for a lookup without a permission prompt.

Search inside the map view

A user looks at a map of Missouri and searches for Springfield. Send the visible map area as a rectangle filter. The values are the west, south, east, and north edges: rect:lon1,lat1,lon2,lat2.

https://api.geoapify.com/v1/geocode/search?text=Springfield&type=city&filter=rect:-95.8,35.9,-89.1,40.6&limit=5&format=json&apiKey=YOUR_API_KEY

Reduced response:

{
  "results": [
    {
      "formatted": "Springfield, IL, United States of America",
      "state_code": "IL",
      "lon": -89.6439575,
      "lat": 39.7990175,
      "result_type": "city",
      "rank": { "confidence": 1 }
    },
    {
      "formatted": "Springfield, MO, United States of America",
      "state_code": "MO",
      "lon": -93.2922715,
      "lat": 37.2081729,
      "result_type": "city",
      "rank": { "confidence": 1 }
    }
  ]
}

Only the two Springfields inside the rectangle are returned. The rectangle covers Missouri and western Illinois, so Springfield, Illinois is inside it too. To put the place nearest to the map centre first, add a proximity bias; see Combine a filter and a bias.

Read the rectangle from your map library when the user searches, for example from map.getBounds() in MapLibre GL JS or Leaflet, and keep longitude before latitude. When the map is zoomed out across the antimeridian, clamp the longitudes to the range from -180 to 180.

Search inside your service area

A delivery service works within 120 km of Columbus, Ohio. Send the service area as a circle filter, circle:lon,lat,radiusMeters:

https://api.geoapify.com/v1/geocode/search?text=Springfield&type=city&filter=circle:-83.0,39.96,120000&limit=5&format=json&apiKey=YOUR_API_KEY

Reduced response:

{
  "results": [
    {
      "formatted": "Springfield, OH, United States of America",
      "city": "Springfield",
      "county": "Clark County",
      "state": "Ohio",
      "state_code": "OH",
      "lon": -83.810138,
      "lat": 39.9234046,
      "result_type": "city",
      "rank": { "confidence": 1 }
    }
  ]
}

Only Springfield, Ohio is inside the circle, so a Springfield in another state can't be selected by mistake. An empty results array means there is no match inside the service area: ask the user to check the spelling, or show a message such as "We don't deliver there yet" instead of a distant match.

Combine a filter and a bias

The filter decides which places can be returned; the bias decides their order. This request searches the Missouri map view from Search inside the map view and ranks the places by distance from a point in Springfield, Missouri, near the map centre:

https://api.geoapify.com/v1/geocode/search?text=Springfield&type=city&filter=rect:-95.8,35.9,-89.1,40.6&bias=proximity:-93.29,37.21&limit=5&format=json&apiKey=YOUR_API_KEY

Reduced response:

{
  "results": [
    {
      "formatted": "Springfield, MO, United States of America",
      "state_code": "MO",
      "lon": -93.2922715,
      "lat": 37.2081729,
      "result_type": "city",
      "distance": 285.9062472124225,
      "rank": { "confidence": 1 }
    },
    {
      "formatted": "Springfield, IL, United States of America",
      "state_code": "IL",
      "lon": -89.6439575,
      "lat": 39.7990175,
      "result_type": "city",
      "distance": 428338.2831187616,
      "rank": { "confidence": 1 }
    }
  ]
}

The same two places come back as with the filter alone, but now Springfield, Missouri is first, 286 metres from the bias point, and Springfield, Illinois second, 428 km away.

Use this pattern for a map search box: the filter keeps results inside the visible area, and the proximity bias to the map centre or the user puts the most likely place first.

Repeated place names with an AI coding agent

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent so that place searches in your project return the place the user means when a name repeats.

Improve the place search in my project with the Geoapify Forward Geocoding API so that repeated names, such as Springfield, return the place the user means.

Before you start
- Inspect the existing project first. Reuse its current framework, search components, map library, HTTP client, and conventions. Make the smallest necessary changes.
- Ask only what the project doesn't answer: what the app knows about the user (their location, the visible map area, a service area, the countries served), and whether a result outside that area should be excluded or only ranked lower.
- Ask me to configure a Geoapify API key before live requests. On a backend, read it from GEOAPIFY_API_KEY. In a browser, ask whether to use a restricted key or a backend proxy. Never hardcode, print, or log the key.

API flow
1. Send GET https://api.geoapify.com/v1/geocode/search with text, format=json, and limit. Add type=city (or another type) when only one kind of place makes sense.
2. To rank places near the user, add bias=proximity:lon,lat. To return only places in the map view, add filter=rect:west,south,east,north. For a service area, add filter=circle:lon,lat,radiusMeters. For countries, add filter=countrycode:us (comma-separated codes).
3. A filter excludes places outside the area; a bias only changes the order. Combine them to search an area and rank inside it, for example filter=rect:... with bias=proximity:<map centre>.

Requirements
- Without a bias, the API uses countrycode:auto and ranks the caller's country first; set bias=countrycode:none if that is unwanted.
- Keep longitude before latitude in proximity, rect, and circle. Clamp map-view longitudes to -180..180.
- limit is a maximum, not a guaranteed count.
- Show formatted (or the state) in the result list, because several results can have the same name.
- Treat an empty results array as "no match in this area" and offer to search a wider area.
- Handle HTTP 400 messages, 401, timeouts, and limited 429 retries with backoff. Debounce typing.

Review the generated code against this guide. Check that it uses a filter only where excluding places is intended, keeps longitude before latitude, shows the state for each result, and handles empty results.