# Google Maps on boxd

> Integrate Google Maps to access location data, geocoding, directions, and mapping services in your application.

- Page: https://boxd.sh/integrations/google-maps/
- CLI: `run google-maps` (23 commands, 14 marked common)
- SDK: `import { googleMaps } from "@boxd/run"`; every parameter and response type is at `@boxd/run/google-maps`
- Triggers: none
- Connect: `run auth google-maps` (Sign in with Google Maps), or https://app.boxd.sh/integrations/detail/google_maps
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth google-maps      # once: prints a link to connect your account
run google-maps           # list its commands
run google-maps geocoding-api --help
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, googleMaps } from "@boxd/run";

every("1 hour", async () => {
  const result = await googleMaps.geocodingApi({});
  console.log(result);
});
```

Run it with `run google-maps.run.ts`. Google Maps has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run google-maps <command> --help` lists the optional ones. "common" marks what `run google-maps` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `autocomplete` ·common | `googleMaps.autocomplete()` | `--input` | 11 | Returns place and query predictions for text input |
| `compute-route-matrix` ·common | `googleMaps.computeRouteMatrix()` | `--destinations` `--origins` | 5 | Calculates travel distance and duration matrix between multiple origins and destinations using the modern Routes API; supports OAuth2 authentication and various travel modes |
| `distance-matrix-api` ·common ·deprecated | `googleMaps.distanceMatrixApi()` | `--destinations` `--origins` | 11 | Legacy API that calculates travel distance and time for a matrix of origins and destinations |
| `geocode-address` ·common ·deprecated | `googleMaps.geocodeAddress()` | — | 6 | Legacy API to convert street addresses into geographic coordinates (latitude and longitude) |
| `geocode-address-with-query` ·common | `googleMaps.geocodeAddressWithQuery()` | `--address-query` | 2 | Map addresses to geographic coordinates with query parameter |
| `geocode-destinations` | `googleMaps.geocodeDestinations()` | — | 6 | Perform destination lookup and return detailed destination information including primary place, containing places, sub-destinations, landmarks, entrances, and navigation points |
| `geocode-location` ·common | `googleMaps.geocodeLocation()` | `--latitude` `--longitude` | 3 | Convert geographic coordinates (latitude and longitude) to human-readable addresses using reverse geocoding |
| `geocode-place` ·common | `googleMaps.geocodePlace()` | `--place-id` | 2 | Perform geocode lookup using a place identifier to retrieve address and coordinates |
| `geocoding-api` ·common | `googleMaps.geocodingApi()` | — | 11 | Convert addresses into geographic coordinates (latitude and longitude) and vice versa (reverse geocoding), or get an address for a Place ID |
| `geolocate` | `googleMaps.geolocate()` | — | 7 | Determine location based on cell towers and WiFi access points |
| `get-direction` | `googleMaps.getDirection()` | `--destination` `--origin` | 5 | Fetches detailed directions between an origin and a destination, supporting intermediate waypoints and various travel modes |
| `get-place-details` ·common | `googleMaps.getPlaceDetails()` | `--name` | 4 | Retrieves comprehensive details for a place using its resource name (places/{place_id} format) |
| `get-route` | `googleMaps.getRoute()` | `--destination-address` `--origin-address` | 9 | Calculates one or more routes between two specified locations |
| `get-time-zone` ·common | `googleMaps.getTimeZone()` | `--location` `--timestamp` | 1 | Retrieves time zone information for a specific geographic location and timestamp |
| `get2d-tile` | `googleMaps.get2dTile()` | `--session` `--x` `--y` `--z` | 2 | Retrieve a 2D map tile image at specified coordinates for building custom map visualizations |
| `get3d-tiles-root` | `googleMaps.get3dTilesRoot()` | — | 1 | Retrieve the 3D Tiles tileset root configuration for photorealistic 3D map rendering |
| `lookup-aerial-video` | `googleMaps.lookupAerialVideo()` | — | 2 | Look up an aerial view video by address or video ID |
| `maps-embed-api` ·common | `googleMaps.mapsEmbedApi()` | `--mode` | 6 | Generate an embeddable Google Map URL and HTML iframe code |
| `nearby-search` | `googleMaps.nearbySearch()` | `--latitude` `--longitude` `--radius` | 4 | Searches for places (e.g., restaurants, parks) within a specified circular area, with options to filter by place types and customize the returned fields and number of results |
| `place-photo` ·common | `googleMaps.placePhoto()` | `--photo-reference` | 2 | Retrieves high quality photographic content from the Google Maps Places database |
| `render-aerial-video` ·common | `googleMaps.renderAerialVideo()` | `--address` | 0 | Starts rendering an aerial view video for a US postal address |
| `text-search` ·common | `googleMaps.textSearch()` | `--textQuery` | 2 | Searches for places on Google Maps using a textual query (e.g., "restaurants in London", "Eiffel Tower") |
| `tiles-create-session` | `googleMaps.tilesCreateSession()` | `--language` `--mapType` `--region` | 6 | Create a session token required for accessing 2D Tiles and Street View imagery |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.