Place API

All endpoints require a Firebase ID token in the Authorization: Bearer <token> header. A missing or invalid token returns 401 UNAUTHORIZED.

Place results follow PlaceSchema. Place data is never persisted by 95octane — every call hits the Google Places API.

---

Get Place Details

GET /place/details/:id?regionCode=<string>&languageCode=<string>

Auth: Bearer token (Firebase ID token)

Get details for a specific place. :id is the raw Google place ID (e.g., ChIJyWEHuEmuEmsRm9hTkapTCrk) without the places/ prefix; the service prepends it before calling Google.

Query Parameters

Parameter	Type	Required	Description
regionCode	string	yes	CLDR region code (e.g., "IN", "US")
languageCode	string	yes	BCP-47 language code (e.g., "en", "hi")

Response 200 — single Place:

{
  "id": "ChIJ...",
  "name": "places/ChIJ...",
  "displayName": "Prestige Lakeside Habitat",
  "type": "other",
  "formattedAddress": "Varthur, Bengaluru, Karnataka 560087, India",
  "businessStatus": "OPERATIONAL",
  "googleMapsUri": "https://maps.google.com/?cid=...",
  "location": { "lat": 12.9353, "lng": 77.7142 },
  "photosName": ["places/ChIJ.../photos/..."],
}

Errors

Status	Code	Condition
400	MISSING_FIELD	regionCode or languageCode not provided
400	INVALID_FIELD	regionCode or languageCode is not in the supported list
401	UNAUTHORIZED	No valid Firebase ID token
500	PLACES_SEARCH_FAILED	Upstream Google Places API call failed
500	PLACE_TRANSFORM_FAILED	Google returned a response that could not be normalized to a Place

---

Search Places

POST /place/search

Auth: Bearer token (Firebase ID token)

Search for places using the Google Places API text search.

Request

Field	Type	Required	Description
text	string	yes	Text query (e.g., "fuel station near MG Road")
regionCode	string	yes	CLDR region code (e.g., "IN", "US")
languageCode	string	yes	BCP-47 language code (e.g., "en", "hi")
currentLocation	{lat, lng}	no	User's current coordinates for geographic bias
radius	number	no	Bias radius in metres (5000–500000); requires currentLocation

When both currentLocation and radius are provided, results are biased toward that area. If either is omitted, an unbiased global search is performed.

Response 200

[
  {
    "id": "ChIJ...",
    "name": "places/ChIJ...",
    "displayName": "Prestige Lakeside Habitat",
    "type": "other",
    "formattedAddress": "Varthur, Bengaluru, Karnataka 560087, India",
    "businessStatus": "OPERATIONAL",
    "googleMapsUri": "https://maps.google.com/?cid=...",
    "location": { "lat": 12.9353, "lng": 77.7142 },
    "photosName": ["places/ChIJ.../photos/..."],
  },
]

Errors

Status	Code	Condition
400	MISSING_FIELD	text, regionCode, or languageCode not provided
400	INVALID_FIELD	text is empty; radius outside 5000–500000; unsupported region/lang
401	UNAUTHORIZED	No valid Firebase ID token
500	PLACES_SEARCH_FAILED	Upstream Google Places API call failed
500	PLACES_TRANSFORM_FAILED	Google returned a response that could not be normalized to Place[]

---

Get Place Photo

POST /place/photo

Auth: Bearer token (Firebase ID token)

Resolves a photo resource name (from Place.photosName[]) into a time-limited Google CDN URL the client can fetch directly. The server adds the /media suffix internally; clients pass the raw photosName value.

Request

Field	Type	Required	Description
name	string	yes	Photo resource name from PlaceSchema.photosName[] (e.g., "places/ChIJ.../photos/AF1QipO...")
maxWidth	number	no	Max width in pixels (> 0); defaults to 1024
maxHeight	number	no	Max height in pixels (> 0); defaults to 1024

Response 200

{
  "name": "places/ChIJ.../photos/AF1QipO...",
  "photoUri": "https://lh3.googleusercontent.com/places/...", // short-lived signed URL
}

Errors

Status	Code	Condition
400	MISSING_FIELD	name not provided
400	INVALID_FIELD	name is empty; maxWidth or maxHeight ≤ 0
401	UNAUTHORIZED	No valid Firebase ID token
500	PLACES_PHOTO_FAILED	Upstream Google Places API call failed
500	PLACES_TRANSFORM_FAILED	Google returned a response missing name or photoUri