# gmaps

Search Google Maps from the command line. Look up any place and get ratings, categories, phone numbers, websites, and more — no API key required. Also fetch every place from a public saved list.

Designed for use with LLMs and AI agents — structured JSON output, simple commands, no auth flows. See [`AGENT.md`](./AGENT.md) for agent-specific instructions.

## Install

Requires [Bun](https://bun.sh).

```bash
# Run directly
bunx @kvendrik/gmaps search "Eiffel Tower"

# Or install globally
bun install -g @kvendrik/gmaps
```

## Usage

### Search for a place

```bash
gmaps search "Mitts Restaurant Amsterdam"
gmaps search "Eiffel Tower" -f json
```

### Fetch a saved list

```bash
# Fetch all places from a public Google Maps list
gmaps list https://maps.app.goo.gl/your-list-url

# Filter by name or address
gmaps list https://maps.app.goo.gl/your-list-url -q Amsterdam

# Enrich with ratings, categories, phone, website
gmaps list https://maps.app.goo.gl/your-list-url -q "De Waaghals" --enrich

# Output as JSON
gmaps list https://maps.app.goo.gl/your-list-url -f json
```

### Save list aliases

```bash
# Save a list with a short name
gmaps lists add wantgo https://maps.app.goo.gl/your-list-url

# Use the alias instead of the URL
gmaps list wantgo -q Amsterdam --enrich

# List saved aliases
gmaps lists ls

# Remove an alias
gmaps lists rm wantgo

# Custom config location
GMAPS_CONFIG=./my-lists.json gmaps lists ls
```

## Commands

| Command | Description |
|---------|-------------|
| `gmaps search <query>` | Look up a place on Google Maps |
| `gmaps list <url\|alias>` | Fetch places from a public Google Maps list |
| `gmaps lists add <alias> <url>` | Save a list URL with an alias |
| `gmaps lists rm <alias>` | Remove a saved alias |
| `gmaps lists ls` | Show all saved aliases |

### Options for `gmaps list`

| Flag | Description | Default |
|------|-------------|---------|
| `-q, --query <text>` | Filter places by name or address | — |
| `-e, --enrich` | Fetch ratings, categories, phone, website | off |
| `-f, --format <type>` | Output format: `json` or `table` | `table` |
| `-d, --delay <ms>` | Delay between enrichment requests | `200` |

## How it works

`gmaps` uses Google Maps' internal APIs — no API key or authentication required.

- **Search** hits the `tbm=map` search endpoint to get ratings, categories, phone numbers, websites, and opening hours.
- **List fetching** hits the `entitylist/getlist` endpoint, which returns all places in a single request (tested with 1,000+ places).
- **Aliases** are stored in `~/.gmaps.json` (override with `GMAPS_CONFIG` env variable).

## Caveats

- These are undocumented Google APIs — they could change without notice.
- Enrichment makes one HTTP request per place. For large lists, use `--delay` to avoid rate limiting.
- Search works best with specific place names. Generic queries like "coffee shops in Amsterdam" won't return results (Google renders those client-side).

## License

MIT