# Get how busy a Google Maps place is now and by hour of the week

Returns how busy a Google Maps place is now, and how busy it usually is each hour of the week. Use it to compare foot traffic between places.

Tool `google.maps.popular-times` on Google. Contract version 1, released 2026-10-27.

## Example call

Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`.

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/google.maps.popular-times/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"place_id":"ChIJT2h1HKZZwokR0kgzEtsa03k"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/google.maps.popular-times/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={"input": {"place_id": "ChIJT2h1HKZZwokR0kgzEtsa03k"}},
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/google.maps.popular-times/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"input": {"place_id": "ChIJT2h1HKZZwokR0kgzEtsa03k"}}),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "google.maps.popular-times",
    "input": {
      "place_id": "ChIJT2h1HKZZwokR0kgzEtsa03k"
    }
  }
}
```

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `place_id` | string | Yes |  | Google Place ID of the place, such as "ChIJT2h1HKZZwokR0kgzEtsa03k". |

## Output

A successful call returns these blocks in its `output`. A field not marked required can be `null`.

### place

One object. Can be `null`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | No | Name of the business or place. |
| `place_id` | string | Yes |  |
| `data_id` | string | No | Google Maps feature ID of the place, in hexadecimal, such as "0x89c259a61c75684f:0x79d31adb123348d2". |

### live

One object. Can be `null`. How busy the place is now. Null when Google shows no live reading, as when the place is closed.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `day` | string | No | Weekday now at the place. One of `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. |
| `hour` | integer | No | Hour of the day now at the place, from 0 to 23. |
| `busyness_score` | integer | Yes | Busyness now, from 0 to 100, on the scale of the usual curve. |
| `usual_busyness_score` | integer | No | Usual busyness at this hour of this weekday, from 0 to 100. |
| `label` | string | No | Google's words for the busyness now, such as "As busy as it gets". |
| `time_spent_label` | string | No | Google's words for a usual visit's length, such as "People typically spend 10-45 min here". |

### usual_busyness

One object. Can be `null`. Google's popular times graph. Each weekday lists its hours in order, in the place's local time. Null when Google publishes no graph for the place.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `monday` | array of object | No |  |
| `monday.hour` | integer | Yes | Hour of the day, from 0 to 23. |
| `monday.busyness_score` | integer | Yes | Usual busyness, from 0 to 100, relative to the place's busiest hour of the week. 0 when the place is closed or usually empty. |
| `monday.label` | string | No | Google's words for the busyness, such as "Usually a little busy". |
| `tuesday` | array of object | No |  |
| `tuesday.hour` | integer | Yes | Hour of the day, from 0 to 23. |
| `tuesday.busyness_score` | integer | Yes | Usual busyness, from 0 to 100, relative to the place's busiest hour of the week. 0 when the place is closed or usually empty. |
| `tuesday.label` | string | No | Google's words for the busyness, such as "Usually a little busy". |
| `wednesday` | array of object | No |  |
| `wednesday.hour` | integer | Yes | Hour of the day, from 0 to 23. |
| `wednesday.busyness_score` | integer | Yes | Usual busyness, from 0 to 100, relative to the place's busiest hour of the week. 0 when the place is closed or usually empty. |
| `wednesday.label` | string | No | Google's words for the busyness, such as "Usually a little busy". |
| `thursday` | array of object | No |  |
| `thursday.hour` | integer | Yes | Hour of the day, from 0 to 23. |
| `thursday.busyness_score` | integer | Yes | Usual busyness, from 0 to 100, relative to the place's busiest hour of the week. 0 when the place is closed or usually empty. |
| `thursday.label` | string | No | Google's words for the busyness, such as "Usually a little busy". |
| `friday` | array of object | No |  |
| `friday.hour` | integer | Yes | Hour of the day, from 0 to 23. |
| `friday.busyness_score` | integer | Yes | Usual busyness, from 0 to 100, relative to the place's busiest hour of the week. 0 when the place is closed or usually empty. |
| `friday.label` | string | No | Google's words for the busyness, such as "Usually a little busy". |
| `saturday` | array of object | No |  |
| `saturday.hour` | integer | Yes | Hour of the day, from 0 to 23. |
| `saturday.busyness_score` | integer | Yes | Usual busyness, from 0 to 100, relative to the place's busiest hour of the week. 0 when the place is closed or usually empty. |
| `saturday.label` | string | No | Google's words for the busyness, such as "Usually a little busy". |
| `sunday` | array of object | No |  |
| `sunday.hour` | integer | Yes | Hour of the day, from 0 to 23. |
| `sunday.busyness_score` | integer | Yes | Usual busyness, from 0 to 100, relative to the place's busiest hour of the week. 0 when the place is closed or usually empty. |
| `sunday.label` | string | No | Google's words for the busyness, such as "Usually a little busy". |

## Example output

The `output` of a real call, each list cut to 3 items.

```json
{
  "place": {
    "title": "Stumptown Coffee Roasters",
    "place_id": "ChIJT2h1HKZZwokR0kgzEtsa03k",
    "data_id": "0x89c259a61c75684f:0x79d31adb123348d2"
  },
  "live": {
    "day": "monday",
    "hour": 13,
    "busyness_score": 88,
    "usual_busyness_score": 76,
    "label": "As busy as it gets",
    "time_spent_label": "People typically spend 10-45 min here"
  },
  "usual_busyness": {
    "monday": [
      {
        "hour": 5,
        "busyness_score": 0,
        "label": null
      },
      {
        "hour": 6,
        "busyness_score": 32,
        "label": "Usually not too busy"
      },
      {
        "hour": 7,
        "busyness_score": 43,
        "label": "Usually not too busy"
      }
    ],
    "tuesday": [
      {
        "hour": 5,
        "busyness_score": 0,
        "label": null
      },
      {
        "hour": 6,
        "busyness_score": 32,
        "label": "Usually not too busy"
      },
      {
        "hour": 7,
        "busyness_score": 44,
        "label": "Usually not too busy"
      }
    ],
    "wednesday": [
      {
        "hour": 5,
        "busyness_score": 0,
        "label": null
      },
      {
        "hour": 6,
        "busyness_score": 27,
        "label": "Usually not too busy"
      },
      {
        "hour": 7,
        "busyness_score": 45,
        "label": "Usually not too busy"
      }
    ],
    "thursday": [
      {
        "hour": 5,
        "busyness_score": 0,
        "label": null
      },
      {
        "hour": 6,
        "busyness_score": 32,
        "label": "Usually not too busy"
      },
      {
        "hour": 7,
        "busyness_score": 42,
        "label": "Usually not too busy"
      }
    ],
    "friday": [
      {
        "hour": 5,
        "busyness_score": 0,
        "label": null
      },
      {
        "hour": 6,
        "busyness_score": 25,
        "label": "Usually not too busy"
      },
      {
        "hour": 7,
        "busyness_score": 35,
        "label": "Usually not too busy"
      }
    ],
    "saturday": [
      {
        "hour": 6,
        "busyness_score": 0,
        "label": null
      },
      {
        "hour": 7,
        "busyness_score": 35,
        "label": "Usually not too busy"
      },
      {
        "hour": 8,
        "busyness_score": 44,
        "label": "Usually not too busy"
      }
    ],
    "sunday": [
      {
        "hour": 6,
        "busyness_score": 0,
        "label": null
      },
      {
        "hour": 7,
        "busyness_score": 27,
        "label": "Usually not too busy"
      },
      {
        "hour": 8,
        "busyness_score": 30,
        "label": "Usually not too busy"
      }
    ]
  }
}
```