# Popular Times

Popular times of one Google Maps place: how busy it usually is for every hour of every opening day, the live busyness of the current hour when Google shows it, the typical visit duration and the busiest hours per day. One request costs 3 credits; failed requests and places without popular times are never charged. Pass the business_id (or place_id). The name of the place is read from Google Maps and checked against the result, so you never get the graph of another place. Send q with the exact place name to skip that lookup. Labels are always English. busyness_percent is relative to the busiest hour of the week (100). A value of null marks an hour outside opening time. Closed days are listed in closed_days and are missing from days. peak_hours is derived by Scrappa: the three busiest hours of each day.

- **Documentation:** [https://scrappa.co/docs/google-maps-api/google_maps_popular_times](https://scrappa.co/docs/google-maps-api/google_maps_popular_times)
- **API group:** Google Maps API
- **Endpoint:** `GET https://scrappa.co/api/maps/popular-times`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `business_id` | string | No | Google Maps business in google_id (0x...:0x...) or place_id (ChIJ...) format. Send this or place_id. Example: 0x89c2598f7ff4aa09:0x313547e757cb8cea |
| `place_id` | string | No | Google place_id (ChIJ...). Alternative to business_id. |
| `q` | string | No | Optional exact name of the place, for example Katz's Delicatessen New York. It replaces the name lookup. The Google result must show the same name, otherwise the request answers 404. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/maps/popular-times?business_id=0x89c2598f7ff4aa09%3A0x313547e757cb8cea"
```

## Example response

```json
{
    "place": {
        "business_id": "0x89c2598f7ff4aa09:0x313547e757cb8cea",
        "name": "Katz's Delicatessen",
        "address": "Katz's Delicatessen, 205 E Houston St, New York, NY 10002"
    },
    "current_day": "tuesday",
    "current_hour": 18,
    "live": {
        "day": "tuesday",
        "hour": 18,
        "hour_label": "6 PM",
        "busyness_percent": 51,
        "label": "A little busy",
        "usual_busyness_percent": 78,
        "usual_label": "Usually a little busy",
        "wait_time": null
    },
    "typical_visit_duration": {
        "text": "20 min to 1.5 hr",
        "min_minutes": 20,
        "max_minutes": 90
    },
    "closed_days": [],
    "days": [
        {
            "day": "monday",
            "hours": [
                {
                    "hour": 6,
                    "hour_label": "6 AM",
                    "busyness_percent": null,
                    "label": null,
                    "wait_time": null,
                    "wait_minutes": null
                },
                {
                    "hour": 12,
                    "hour_label": "12 PM",
                    "busyness_percent": 77,
                    "label": "Usually a little busy",
                    "wait_time": null,
                    "wait_minutes": null
                },
                {
                    "hour": 18,
                    "hour_label": "6 PM",
                    "busyness_percent": 84,
                    "label": "Usually as busy as it gets",
                    "wait_time": null,
                    "wait_minutes": null
                }
            ],
            "peak_hours": [
                {
                    "hour": 14,
                    "hour_label": "2 PM",
                    "busyness_percent": 86
                },
                {
                    "hour": 15,
                    "hour_label": "3 PM",
                    "busyness_percent": 87
                },
                {
                    "hour": 16,
                    "hour_label": "4 PM",
                    "busyness_percent": 87
                }
            ]
        },
        {
            "day": "tuesday",
            "hours": [
                {
                    "hour": 6,
                    "hour_label": "6 AM",
                    "busyness_percent": null,
                    "label": null,
                    "wait_time": null,
                    "wait_minutes": null
                },
                {
                    "hour": 12,
                    "hour_label": "12 PM",
                    "busyness_percent": 79,
                    "label": "Usually a little busy",
                    "wait_time": null,
                    "wait_minutes": null
                },
                {
                    "hour": 18,
                    "hour_label": "6 PM",
                    "busyness_percent": 78,
                    "label": "Usually a little busy",
                    "wait_time": null,
                    "wait_minutes": null
                }
            ],
            "peak_hours": [
                {
                    "hour": 13,
                    "hour_label": "1 PM",
                    "busyness_percent": 87
                },
                {
                    "hour": 14,
                    "hour_label": "2 PM",
                    "busyness_percent": 89
                },
                {
                    "hour": 15,
                    "hour_label": "3 PM",
                    "busyness_percent": 87
                }
            ]
        }
    ],
    "credits_charged": 3
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | No business_id or place_id was sent, or a value is malformed. This response is not billed. |
| 404 | No Popular Times | Google Maps has no place for this id, Google shows no popular times for it, or the result shows another place. This response is not billed. |
| 503 | Popular Times Temporarily Unavailable | No Google session could read the result. Retry after the Retry-After interval; this response is not billed. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)