Maps Search
Text search across Google Maps — full place data sourced live from the Google Places API (New). Ratings, reviews, hours, photos, contact info, amenities, and coordinates for any query.
/v1/maps/searchA live text search across Google Maps that returns rich, structured place data — sourced directly from the official Google Places API (New), not a SERP scrape. Send any natural-language query ("coffee in seattle", "24h pharmacy near london bridge", "electric car chargers manhattan") and get back full business profiles in one call.
Usage
const res = await fetch('https://api.yepapi.com/v1/maps/search', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
query: 'coffee in seattle',
limit: 10,
language: 'en',
region: 'us',
}),
});
const { data } = await res.json();
console.log(data.results[0]);curl -X POST https://api.yepapi.com/v1/maps/search \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "coffee in seattle", "limit": 10, "language": "en", "region": "us"}'Request Body
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
query | string | Yes | Text query, e.g. "coffee in seattle", "restaurants near times square". | — |
limit | number | No | Number of places to return (1–20). Use nextPageToken for more. | 10 |
language | string | No | BCP-47 language code (e.g. en, es, fr). | "en" |
region | string | No | CLDR region code (e.g. us, gb, de). Biases results to a country. | — |
location_bias | object | No | Prefer results around a point or area. A circle { latitude, longitude, radius_m } (radius 1–50000 meters) or a rectangle { low, high }. Results outside it can still appear. | — |
location_restriction | object | No | Hard limit: only return places inside a rectangle { low, high }. Cannot be combined with location_bias. | — |
rank_preference | string | No | relevance or distance. distance orders results by distance from the bias point. | "relevance" |
open_now | boolean | No | Only return places that are open right now. | — |
min_rating | number | No | Minimum average rating (0.0–5.0). | — |
price_levels | string[] | No | Any of free, inexpensive, moderate, expensive, very_expensive. | — |
included_type | string | No | Restrict to one Google place type, e.g. restaurant, plumber. | — |
page_token | string | No | nextPageToken from the previous response. See Pagination. | — |
Searching from a point
Add location_bias to run a query as if from a specific coordinate. Repeat the same query from a grid of points around a business to see where it ranks from each one.
curl -X POST https://api.yepapi.com/v1/maps/search \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "plumber",
"limit": 20,
"location_bias": { "latitude": 30.2672, "longitude": -97.7431, "radius_m": 2000 },
"rank_preference": "relevance"
}'A bias is a preference, not a filter: Google may still return a strong match from outside the circle. For a hard boundary, send location_restriction with the south-west (low) and north-east (high) corners instead:
{
"query": "plumber",
"location_restriction": {
"low": { "latitude": 30.25, "longitude": -97.76 },
"high": { "latitude": 30.29, "longitude": -97.72 }
}
}The top-level latitude, longitude and radius parameters are an equivalent shorthand for a circular location_bias. A location that is incomplete or out of range returns a 400 validation error and is not billed.
Response
{
"ok": true,
"data": {
"query": "coffee in seattle",
"totalResults": 1,
"nextPageToken": "AU_ZVEFqNRxa-OTq...",
"searchUrl": "https://www.google.com/maps/search/coffee+in+seattle",
"results": [
{
"id": "ChIJBR3G8LJqkFQRWD2Wzn0qG3c",
"name": "Storyville Coffee Company",
"types": ["coffee_shop", "cafe", "store", "food", "point_of_interest", "establishment"],
"primaryType": "coffee_shop",
"address": "94 Pike St #34, Seattle, WA 98101, USA",
"phone": "(206) 780-5777",
"website": "https://www.storyville.com/",
"googleMapsUrl": "https://maps.google.com/?cid=8006338809770720088",
"latitude": 47.6089519,
"longitude": -122.3405629,
"rating": 4.6,
"userRatingCount": 1842,
"priceLevel": "moderate",
"businessStatus": "OPERATIONAL",
"openNow": true,
"hours": [
"Monday: 7:00 AM – 6:00 PM",
"Tuesday: 7:00 AM – 6:00 PM",
"Wednesday: 7:00 AM – 6:00 PM",
"Thursday: 7:00 AM – 6:00 PM",
"Friday: 7:00 AM – 6:00 PM",
"Saturday: 7:00 AM – 6:00 PM",
"Sunday: 7:00 AM – 6:00 PM"
],
"amenities": {
"dineIn": true,
"takeout": true,
"delivery": false,
"servesCoffee": true,
"servesBreakfast": true,
"servesDessert": true,
"goodForGroups": true,
"outdoorSeating": false
},
"photos": [
{
"reference": "places/ChIJBR3G8LJqkFQRWD2Wzn0qG3c/photos/AU_ZVEFd3Y9YtVSYWUZf4lYRda5p51TB2iSOLW...",
"width": 1200,
"height": 800,
"attribution": "Storyville Coffee Company",
"googleMapsUrl": "https://www.google.com/maps/place//data=!3m4!1e2!3m2!..."
}
],
"topReview": {
"rating": 5,
"text": "Hands down the best latte and cinnamon roll in Pike Place. Cozy spot with a view over the market.",
"author": "Marcus Bell",
"publishedAt": "2026-05-18T16:04:11Z",
"relativeTime": "2 months ago"
},
"directionsUrl": "https://www.google.com/maps/dir//...",
"reviewsUrl": "https://www.google.com/maps/place//..."
}
]
}
}Response Fields
| Field | Type | Description |
|---|---|---|
data.query | string | Echo of the text query you submitted. |
data.totalResults | number | Number of places returned in this response (≤ limit). |
data.nextPageToken | string? | Pagination token. Include in your next request to fetch more results. |
data.searchUrl | string? | Direct Google Maps search URL for the same query. |
data.results[].id | string | Stable Google Place ID — pass it to Place Details or Place Reviews. |
data.results[].name | string | Display name as shown on Google Maps. |
data.results[].types | string[] | All place categories Google associates with this place. |
data.results[].primaryType | string | Primary place type, e.g. coffee_shop, restaurant, gym. |
data.results[].address | string | Full formatted street address. |
data.results[].phone | string? | National format phone number. |
data.results[].website | string? | Business website URL. |
data.results[].googleMapsUrl | string? | Direct Google Maps URL for the place. |
data.results[].latitude / longitude | number | Geographic coordinates. |
data.results[].rating | number? | Average star rating (0.0–5.0). |
data.results[].userRatingCount | number? | Total number of user ratings. |
data.results[].priceLevel | string? | One of free, inexpensive, moderate, expensive, very_expensive. |
data.results[].businessStatus | string? | OPERATIONAL, CLOSED_TEMPORARILY, or CLOSED_PERMANENTLY. |
data.results[].openNow | boolean? | Whether the place is open right now. |
data.results[].hours | string[]? | Array of weekday-formatted opening hours strings. |
data.results[].amenities | object? | Boolean flags: dineIn, takeout, delivery, servesCoffee, servesBreakfast, outdoorSeating, goodForGroups, etc. |
data.results[].photos | object[]? | Place photos with reference, width, height, attribution, googleMapsUrl. |
data.results[].topReview | object? | Most recent featured review: rating, text, author, publishedAt, relativeTime. |
data.results[].directionsUrl / reviewsUrl | string? | Deep links into Google Maps. |
Pagination
When more results exist, the response includes a nextPageToken. Send the same request again with page_token set to that value to fetch the next page. Every other parameter must be identical to the original request. Each page is billed as one call.
Pricing
$0.07 per call regardless of how many places are returned. No monthly minimums.
This endpoint queries the Google Places API (New) directly (places:searchText). All fields are sourced from Google Maps in real time and normalized into the response shape above.