# Google Maps

`GET https://api.serpwiz.com/v1/google/maps`

Search Google Maps and get places back as JSON: name, category, address, coordinates, rating, review count, phone, website, opening hours and more. **Costs 1 query** per successful request, for up to 20 places.

```bash
curl "https://api.serpwiz.com/v1/google/maps?q=coffee+shops+in+seattle&num=10" \
  -H "X-API-Key: $SERPWIZ_API_KEY"
```

## Parameters

Provide **one of** `q`, `place_id` or `url`.

| Parameter | Description |
|---|---|
| `q` | What to search for, e.g. `dentists in Miami`. Alias: `query`. |
| `place_id` | A Google Place ID, e.g. `ChIJN1t_tDeuEmsRUsoyG83frY4`, to fetch one place. |
| `url` | A Google Maps URL (`https://www.google.com/maps/…`). |
| `num` | Places to return, `1`–`20`. Default `10`. |
| `gl` | Country code, e.g. `us`, `ca`. Default `us`. |
| `hl` | Language code, e.g. `en`. |
| `location` | Free-text area to search in, e.g. `Toronto, ON`. |
| `lat`, `lng` | Search centre as decimal coordinates. |
| `zoom` | Map zoom level, `1`–`21`. |
| `radius_km` | Search radius around `lat`/`lng`, in kilometres (max 100). |

### Extra detail (slower)

These fetch more data per place, so requests take longer. Turn on only what you need.

| Parameter | Description |
|---|---|
| `place_details=1` | Full place details. |
| `reviews=1` | Include reviews. Use `max_reviews` (`1`–`50`) to limit them. |
| `images=1` | Include photos. Use `max_images` (`1`–`20`) to limit them. |
| `popular_times=1` | Include "popular times" histograms where Google has them. |

## Response

```json
{
  "results": [
    {
      "position": 1,
      "title": "Storyville Coffee Pike Place",
      "categoryName": "Coffee shop",
      "categories": ["Coffee shop", "Bakery", "Cafe"],
      "address": "94 Pike St Top floor Suite 34, Seattle, WA 98101, United States",
      "city": "Seattle",
      "state": "Washington",
      "postalCode": "98101",
      "countryCode": "US",
      "location": { "lat": 47.6087916, "lng": -122.3400457 },
      "rating": 4.6,
      "reviewsCount": 3231,
      "phone": "+1 206-780-5777",
      "website": "https://storyville.com/pages/pike-place-market",
      "placeId": "ChIJBR3G8LJqkFQRWD2Wzn0qG3c",
      "googleMapsUrl": "https://www.google.com/maps/place/?q=place_id:ChIJBR3G8LJqkFQRWD2Wzn0qG3c",
      "openingHours": { "Monday": "6:59 AM–5 PM", "…": "…" },
      "openingHoursState": "Closed · Opens 6:59 AM Mon",
      "priceLevel": null,
      "permanentlyClosed": null
    }
  ]
}
```

### Common fields

| Field | Description |
|---|---|
| `position` | Rank in the results. |
| `title` | Place name. |
| `categoryName`, `categories[]` | Primary and all Google categories. |
| `address`, `street`, `city`, `state`, `postalCode`, `countryCode`, `neighborhood` | Address parts. |
| `location.lat`, `location.lng` | Coordinates. |
| `rating`, `reviewsCount` | Star rating and number of reviews. |
| `phone`, `website`, `domain` | Contact details. |
| `placeId`, `cid`, `googleMapsUrl` | Identifiers and a link to the place. |
| `openingHours`, `openingHoursDetailed[]`, `openingHoursState` | Hours by day and current state. |
| `priceLevel`, `temporarilyClosed`, `permanentlyClosed` | Status fields; `null` when unknown. |
| `imageUrl`, `thumbnailUrl`, `images[]` | Photos. |
| `amenities` | Grouped attributes (accessibility, service options…). |

Places carry many more fields; fields with no data are `null`. Responses always wrap places in `results`.