Unified search

Overview

GET /search is the single-field façade. A general search box shouldn’t have to guess which index to call, so /search fans out server-side to the predictive gazetteer (postcodes, towns, streets, landmarks) AND the amenity index (restaurants, hotels, EV charge points… by name), then blends the two into one ranked list.

That means a query like "Premier Inn York", "Nando’s" or "Pizza Express" resolves here — where /predict (addresses and landmarks only) returns nothing. Authenticate with a key scoped to "predict"; send it as an x-api-key header, or ?key= for a browser (publishable) key locked to your origins. Each call is metered.

Request

GET /search with the typed query. Optionally pass a location bias (usually the current map centre) to float nearby businesses to the top.

curl "https://api.goggleplaces.com/search?q=premier%20inn%20york&mode=all&key=gk_live_pk_..."

Parameters

q — the typed text (required). mode — all (default, blend both) | addresses (gazetteer only, for a checkout address field) | places (amenities only, for a store locator). lat, lng — optional location bias for the places half. limit — 1..100 (default 8; raise it for a store locator that needs every branch in an area). locale — en-GB (default). distance_unit — mi | km.

Modes

all blends addresses and places. addresses restricts to the gazetteer — the same result set as /predict, ideal when you only want postcodes/streets/towns. places restricts to named amenities — ideal for a store-locator that only searches your kind of business.

Location bias

Three ways to pin a search to a place. Location bias: pass lat/lng and nearby matches rank first (a distance decay) — typing travelodge over Manchester surfaces the Manchester branches. Brand + town: just name it — travelodge bedford, nando’s manchester — and /search narrows the brand to that town (or a London area like covent garden), ranked by distance. Category + town: cinema bedford / supermarkets london returns every place of that category near the town. Possessive brands work typed either way — mcdonalds matches McDonald’s.

Response

hits[] ordered by match quality then relevance. Each hit has kind ("address" for gazetteer, "place" for a named amenity), type (town/postcode/street/poi, or the amenity category), display_name, geo_point and an inline icon. Place hits also carry category and locality — the nearest town, folded into display_name so similarly-named businesses are distinguishable ("Ruby Fish Bar, Leeds").

{
  "q": "premier inn york",
  "mode": "all",
  "total": 3,
  "hits": [
    {
      "id": "osm:w123",
      "display_name": "Premier Inn York South West, York",
      "kind": "place",
      "type": "lodging",
      "category": "lodging",
      "locality": "York",
      "geo_point": { "lat": 53.93, "lon": -1.13 }
    },
    {
      "id": "osopen:...",
      "display_name": "York, North Yorkshire",
      "kind": "address",
      "type": "town",
      "geo_point": { "lat": 53.96, "lon": -1.08 }
    }
  ]
}

Related endpoints

/predict is the addresses-only typeahead (identical to mode=addresses). /nearby returns POIs by proximity + category rather than by typed name. Chain /search straight into /directions — a hit’s geo_point is a valid route endpoint, so you can route to a hotel or restaurant, not just an address.