GET /api/maps/search/quickQuick place search
Up to 20 ranked places with available details. Supports query-only search, text location, coordinates, country, language, zoom and start offsets.
Pre-launch contract · locally validated 2026-07-02
Google Maps API for structured business data
Search ranked local places, fetch one richest-available business record, or page through public reviews. Every response uses one normalized JSON contract and reports partial detail honestly.
10 lifetime Quick calls for new accountsUp to 100 places per Deep callPay as you go
Four endpoints
Pick the smallest call that fits the job
Search by query and location, identify one place, or retrieve reviews without mixing contracts.
GET /api/maps/searchDeep place search
Attempts positions 1–100, preserves discovered rank order, and returns unfinished records as explicit core_only entries rather than dropping them.
GET /api/maps/placePlace details
One richest-available record selected by exactly one place_id, data_id, or Google Maps URL.
GET /api/maps/reviewsPlace reviews
Up to 20 reviews per call with reviewer fields, owner responses and an opaque token for the next page. Sort by relevant, newest, highest or lowest.
Tested example
One request, normalized records
This cURL shape was tested against the local API on 2026-07-02. Set the base URL explicitly so the same command works during local validation.
cURL · Quick search
BASE_URL="${SERPENT_BASE_URL:-http://localhost:3001}"
curl --get "$BASE_URL/api/maps/search/quick" \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode "q=coffee" \
--data-urlencode "location=New York, NY" \
--data-urlencode "country=us"The eventual public route is the same path on https://apiserpent.com. Verify production availability in the playground before changing the base URL.
Response shape · abbreviated
{
"success": true,
"type": "maps",
"endpoint": "quick",
"places": [{
"rank": 1,
"name": "Example Coffee",
"website": "https://example.com",
"rating": 4.6,
"detail_status": "complete"
}],
"counts": {
"requested": 20,
"returned": 20,
"fully_enriched": 19,
"core_only": 1
},
"meta": { "partial": true }
}Partial responses
A missing detail is not a missing place
Search preserves the ranked core record when full detail does not finish within the request window.
100requested
97discovered
97returned
85complete
12core-only
Measured locally on 2026-07-02: one bounded Deep call completed in 88.2 seconds with 97 returned places, 85 complete and 12
core_only. This is a development measurement, not a production latency promise. Treat nullable detail fields on core_only records as unknown—not absent.Normalized fields
One shape across search and place detail
Richest-available means some fields are nullable. Consumers can depend on field names while checking each record’s detail status.
Identity & rank
rank · place_id · data_id · maps_url · name · description · categories · business_statusContact & location
address.* · coordinates.latitude · coordinates.longitude · phone · website · timezone · plus_codeReputation
rating · review_count · review_distribution · price_range · opening_hoursVisit planning
popular_times · amenities · service_options · links.booking · links.menu · links.order_onlineMedia & ownership
cover_image · image_count · images[] · ownership.claimed · ownership.owner_nameReview records
review_id · rating · text.* · published_at · images[] · detailed_ratings · owner_response · reviewer.*Exact pricing
Maps-specific rates and discounts
Maps does not use the 10×/20× discount schedule applied to the core SERP categories.
| Endpoint | Default | Growth (2× off) | Scale (4× off) |
|---|---|---|---|
| Quickup to 20 places | $0.015/call$15/1K calls | $0.0075/call$7.50/1K | $0.00375/call$3.75/1K |
| Deepup to 100 places | $0.075/call$75/1K calls | $0.0375/call$37.50/1K | $0.01875/call$18.75/1K |
| Placeone place | $0.0015/call$1.50/1K calls | $0.00075/call$0.75/1K | $0.000375/call$0.375/1K |
| Reviewsup to 20 reviews | $0.003/call$3/1K calls | $0.0015/call$1.50/1K | $0.00075/call$0.75/1K |
New accounts receive 10 separate lifetime Quick calls. Deep, Place and Reviews are paid from call one. Valid empty results and successful partial results are billable calls.
Limitations
Use the right location product
This API is for structured business and review data. It is not a map-rendering SDK and does not provide directions, route optimization, navigation, geocoding or autocomplete UI. Search can return fewer than the requested maximum, fields vary by place, and
core_only fields must not be interpreted as confirmed absence. Review order can change over time; follow the returned opaque page token instead of manufacturing offsets.FAQ
Google Maps API questions
Search returns ranked place records with identifiers, address, coordinates, phone, website, rating, hours, categories, status and available detail fields. Place returns one richest-available record. Reviews returns up to 20 public reviews per call with reviewer data and an opaque page token when another page is available.
Per 1,000 calls, Quick costs $15, $7.50 or $3.75; Deep $75, $37.50 or $18.75; Place $1.50, $0.75 or $0.375; and Reviews $3, $1.50 or $0.75 on Default, Growth and Scale. Maps uses its own 2× and 4× discounts.
New accounts receive a separate allowance of 10 lifetime Quick calls. Deep, Place and Reviews use paid credits from the first call.
A core-only search record preserves the discovered rank and available core fields when full detail did not finish within the request window. The response counts complete and core-only records separately and sets
meta.partial to true.No. This product returns structured business, place and review data. It does not render maps or provide directions, route optimization, navigation, geocoding or autocomplete widgets.
The contract and examples on this page have been validated locally. Production availability must be verified in the live playground before integration; this page does not claim that the pre-launch endpoints are deployed.
