How to Search Places by Name or Brand

You know the name of a brand or a place, such as Starbucks, Subway, or Whole Foods Market, and need the matching places near a location. The Geoapify Places API has no separate brand filter. Its name parameter matches the place names in the data, and you combine it with a category and a search area.

Send name together with a broad category such as catering or commercial, a circle filter for the search area, and a proximity bias so the nearest matches come first. Then check the returned names: name matches text, not a brand ID.

How the name parameter matches

name returns places whose name contains the text you send. The table shows what came back for different name values around Pike Place Market in Seattle, with bias=proximity:-122.3421,47.6101:

Place data changes over time, so the counts are an illustration rather than fixed values.

What this means for a brand search:

• Send categories. It is required. A request with name and no categories returns HTTP 400. Use a broad parent category that contains the brand: catering for coffee shops and fast food, commercial for shops and supermarkets. Separate several categories with commas, for example categories=catering,commercial.
• Use the brand's own spelling, including apostrophes. McDonald's and Trader Joe's match; McDonalds and Trader Joes don't. To accept several spellings from users, send one request per spelling.
• Avoid short, common words. A word that appears in many names, such as foods, also returns unrelated places. Send the full brand name and check properties.name in the results.
• Expect names, not brands. A store is found only when your text is part of its name in the data. The API doesn't group differently named stores under one brand.
• Add a search area. Use filter=circle:longitude,latitude,radiusMeters to limit the area and bias=proximity:longitude,latitude to order the results by distance. Without a filter, the proximity bias orders the results but doesn't set a maximum distance.

Request places by name near a location

This request finds Starbucks coffee shops within 1,000 metres of Pike Place Market in Seattle, nearest first:

https://api.geoapify.com/v2/places?categories=catering&name=Starbucks&filter=circle:-122.3421,47.6101,1000&bias=proximity:-122.3421,47.6101&limit=5&apiKey=YOUR_API_KEY

Coordinates in circle and proximity are ordered as longitude, latitude. Encode names with spaces or apostrophes in the URL, for example name=Whole%20Foods or name=Trader%20Joe%27s.

Reduced response: The request returned 5 places, from 37 to 611 metres away. The response below keeps the first two and the fields a store list needs.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Starbucks",
        "housenumber": "1912",
        "street": "Pike Place",
        "city": "Seattle",
        "state": "Washington",
        "postcode": "98101",
        "country": "United States",
        "country_code": "us",
        "formatted": "Starbucks, 1912 Pike Place, Seattle, WA 98101, United States of America",
        "categories": [
          "catering",
          "catering.cafe",
          "catering.cafe.coffee",
          "catering.cafe.coffee_shop",
          "internet_access"
        ],
        "distance": 37,
        "lat": 47.6100077,
        "lon": -122.3425796,
        "place_id": "51b791fcd2ec955ec05941f778bb14ce4740f00103f901195ae68e00000000920309537461726275636b73"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-122.3425796, 47.6100077]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "name": "Starbucks",
        "housenumber": "1401",
        "street": "2nd Avenue",
        "city": "Seattle",
        "state": "Washington",
        "postcode": "98101",
        "country": "United States",
        "country_code": "us",
        "formatted": "Starbucks, 1401 2nd Avenue, Seattle, WA 98101, United States of America",
        "categories": [
          "catering",
          "catering.cafe",
          "catering.cafe.coffee",
          "catering.cafe.coffee_shop"
        ],
        "distance": 332,
        "lat": 47.6082644,
        "lon": -122.3386109,
        "place_id": "516d640dcdab955ec05920b99c9bdbcd4740f00103f901edfb193902000000920309537461726275636b73"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-122.3386109, 47.6082644]
      }
    }
  ]
}

Read the results this way:

• properties.name is the matched name. Check it when the search text is short or common.
• properties.distance is the distance in metres from the proximity point. It is a straight-line distance, not a walking or driving distance.
• geometry.coordinates is [longitude, latitude]; lat and lon hold the same position.
• Keep properties.place_id to request Place Details later, such as opening hours or a website.

An empty features array means no place with that name is in the search area. Widen the circle, check the spelling, or try another category.

Brand search with an AI coding agent

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent to add a "find the nearest stores of a brand" search to your project.

Add a "find the nearest stores of a brand" search to my project with the Geoapify Places API.

Before you start
- Inspect the existing project first. Reuse its current framework, components, styling, HTTP client, map library, and conventions. Make the smallest necessary changes.
- Ask only what the project doesn't answer: where the search point comes from (map click, user location, or an address), which radius to use, and how many results to show.
- 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/v2/places with categories, name, filter=circle:lon,lat,radiusMeters, bias=proximity:lon,lat, and limit.
2. categories is required. Use a broad parent category that contains the brand, such as catering for coffee shops and fast food or commercial for shops; several categories are comma-separated.
3. Read the places from features. Each feature has properties.name, properties.formatted, properties.distance (metres from the proximity point), properties.place_id, and geometry.coordinates in [longitude, latitude] order.

Requirements
- name matches place names, not a brand ID: case doesn't matter and a part of the name matches, but punctuation such as apostrophes must match. Show properties.name in the results so users can see what matched.
- URL-encode the name. Send longitude before latitude in circle and proximity.
- Treat an empty features array as "no stores in this area" and suggest a larger radius.
- Ignore results from an older request when the user changes the brand or the point quickly.
- Handle HTTP 400 messages, 401, timeouts, and limited 429 retries with backoff.
- Show a loading state while the request runs, and keep the "Powered by Geoapify" attribution visible.

Review the generated code against the request in this guide. Check that it sends categories with name, keeps longitude before latitude, encodes the name, shows the matched names, and handles empty results and API-key storage.