> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/google-maps.md).

# Google Maps

Google Maps: place search, place details, and place reviews.

## Search Google Maps places

> Search Google Maps for places by free-text \`query\`. Use \`offset\` (a numeric string) to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive). Optional geo filters: \`latitude\`, \`longitude\`, \`zoom\`.\
> \
> \*\*Cost: 500 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"google-maps","description":"Google Maps: place search, place details, and place reviews."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"GoogleMapsPlaceSearchResult":{"type":"object","description":"Place result returned by /google-maps/place/search.","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"address":{"type":"string"},"neighborhood":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"district":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"location":{"$ref":"#/components/schemas/GoogleMapsLocation"},"website":{"type":"string","format":"uri","nullable":true},"phone":{"type":"string","nullable":true},"price":{"type":"string","nullable":true},"totalScore":{"type":"number","format":"float"},"placeId":{"type":"string"},"fid":{"type":"string","description":"Google Maps feature ID, of the form '0x...:0x...'."},"reviewsCount":{"type":"integer"},"categories":{"type":"array","items":{"type":"string"}},"openingHours":{"type":"array","description":"Opening hours per weekday.","items":{"type":"object","additionalProperties":true}},"additionalInfo":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"boolean"}},"description":"Grouped feature flags (e.g. Service options, Accessibility, Offerings)."}}},"GoogleMapsLocation":{"type":"object","description":"Latitude/longitude pair.","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/google-maps/place/search":{"get":{"operationId":"searchGoogleMapsPlaces","summary":"Search Google Maps places","description":"Search Google Maps for places by free-text `query`. Use `offset` (a numeric string) to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive). Optional geo filters: `latitude`, `longitude`, `zoom`.\n\n**Cost: 500 credits/request + 1 credit/item**","tags":["google-maps"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5}},{"name":"languageCode","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":10}},{"name":"latitude","in":"query","required":false,"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},{"name":"longitude","in":"query","required":false,"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},{"name":"zoom","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d+(\\.\\d+)?$"}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d+$"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GoogleMapsPlaceSearchResult"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get a Google Maps place by FID

> Returns full details for a Google Maps place identified by its FID (e.g. \`0x47e671d877937b0f:0xb975fcfa192f84d4\`).\
> \
> \*\*Cost: 500 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"google-maps","description":"Google Maps: place search, place details, and place reviews."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"GoogleMapsPlace":{"type":"object","description":"Full place detail returned by /google-maps/place/{fid}.","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"address":{"type":"string"},"neighborhood":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"district":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"location":{"$ref":"#/components/schemas/GoogleMapsLocation"},"website":{"type":"string","format":"uri","nullable":true},"phone":{"type":"string","nullable":true},"phoneUnformatted":{"type":"string","nullable":true},"plusCode":{"type":"string","nullable":true},"price":{"type":"string","nullable":true},"totalScore":{"type":"number","format":"float"},"placeId":{"type":"string"},"cid":{"type":"string"},"fid":{"type":"string"},"reviewsCount":{"type":"integer"},"reviewsDistribution":{"$ref":"#/components/schemas/GoogleMapsReviewsDistribution"},"categories":{"type":"array","items":{"type":"string"}},"additionalInfo":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"boolean"}},"description":"Grouped feature flags (e.g. Service options, Accessibility, Amenities)."}}},"GoogleMapsLocation":{"type":"object","description":"Latitude/longitude pair.","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"GoogleMapsReviewsDistribution":{"type":"object","properties":{"oneStar":{"type":"integer"},"twoStar":{"type":"integer"},"threeStar":{"type":"integer"},"fourStar":{"type":"integer"},"fiveStar":{"type":"integer"}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/google-maps/place/{fid}":{"get":{"operationId":"getGoogleMapsPlace","summary":"Get a Google Maps place by FID","description":"Returns full details for a Google Maps place identified by its FID (e.g. `0x47e671d877937b0f:0xb975fcfa192f84d4`).\n\n**Cost: 500 credits/request + 1 credit/item**","tags":["google-maps"],"parameters":[{"name":"fid","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]+:0x[a-fA-F0-9]+$"}},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5}},{"name":"languageCode","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":10}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GoogleMapsPlace"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get reviews for a Google Maps place

> Returns reviews for a place identified by its full Google Maps URL. Use \`cursor\` to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive).\
> \
> \*\*Cost: 160 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"google-maps","description":"Google Maps: place search, place details, and place reviews."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"GoogleMapsPlaceReview":{"type":"object","properties":{"id":{"type":"string"},"link":{"type":"string","format":"uri"},"text":{"type":"string"},"stars":{"type":"integer","minimum":1,"maximum":5},"date":{"type":"integer","description":"Unix timestamp in milliseconds"},"dateIso":{"type":"string","format":"date-time"},"likes":{"type":"integer","nullable":true},"photos":{"type":"array","items":{"type":"string"}},"reviewer":{"$ref":"#/components/schemas/GoogleMapsReviewer"},"ownersResponse":{"type":"object","additionalProperties":true,"description":"Owner's response to the review (empty object when none)."},"details":{"type":"object","additionalProperties":{"type":"string"},"description":"Free-form key/value pairs of review metadata (e.g. \"Visited on\", \"Wait time\")."}}},"GoogleMapsReviewer":{"type":"object","properties":{"name":{"type":"string"},"photo":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"},"totalReviews":{"type":"integer"},"totalPhotos":{"type":"integer"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/google-maps/place/reviews":{"get":{"operationId":"getPlaceReviews","summary":"Get reviews for a Google Maps place","description":"Returns reviews for a place identified by its full Google Maps URL. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).\n\n**Cost: 160 credits/request + 1 credit/item**","tags":["google-maps"],"parameters":[{"name":"placeUrl","in":"query","required":true,"schema":{"type":"string","minLength":10,"maxLength":1000,"format":"uri"}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GoogleMapsPlaceReview"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```