goplaces 📍

goplaces is a Go client and CLI for Google Places API (New) and selected Routes API workflows. It is for terminal use, shell automation, agents, and Go programs that need typed requests and JSON output without hand-building field masks or request payloads.

Install

Homebrew installs the published binary on macOS or Linux:

brew install --cask openclaw/tap/goplaces

With Go 1.26.6 or newer:

go install github.com/steipete/goplaces/cmd/goplaces@latest

Prebuilt archives and checksums are available from GitHub Releases.

Quick start

Enable Places API (New) in a Google Cloud project, create an API key, then run:

export GOOGLE_PLACES_API_KEY="..."
goplaces search "coffee near Central Park" --limit 5
goplaces search "coffee near Central Park" --limit 5 --json

The default output is compact text for people; --json emits the response shape for scripts and agents. See API key setup for API enablement, key restrictions, billing, and quota guidance.

Commands

Command	What it does
search	Finds places by text, filters, and optional location bias.
nearby	Finds places inside a latitude, longitude, and radius.
autocomplete	Returns place and query suggestions for partial input.
details	Fetches place details, with optional reviews and photos.
photo	Resolves a Places photo resource to a media URL.
resolve	Resolves free-form location text to place candidates.
route	Samples a route and searches for places near its waypoints.
directions	Returns distance, duration, warnings, and optional steps.

Run goplaces <command> --help for the current flags. Long flags accept both --flag value and --flag=value.

The route and directions commands also require Routes API. Directions default to walking with metric units and support driving comparisons, route modifiers, and departure or transit arrival times.

Configuration

GOOGLE_PLACES_API_KEY supplies the API key to the CLI and Go client. The same key can access both APIs when they are enabled in one Google Cloud project.

These endpoint overrides are intended for tests, proxies, and mock servers:

Environment variable	Default
GOOGLE_PLACES_BASE_URL	https://places.googleapis.com/v1
GOOGLE_ROUTES_BASE_URL	https://routes.googleapis.com
GOOGLE_DIRECTIONS_BASE_URL	https://routes.googleapis.com

Global flags include --api-key, --timeout, --json, and --no-color. Command-specific examples and response details live at goplaces.sh.

Go client

The root module exposes the same search, nearby, autocomplete, details, photo, resolve, route, and directions workflows as typed Go methods.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/steipete/goplaces"
)

func main() {
	client := goplaces.NewClient(goplaces.Options{APIKey: os.Getenv("GOOGLE_PLACES_API_KEY")})
	result, err := client.Search(context.Background(), goplaces.SearchRequest{Query: "coffee", Limit: 5})
	if err != nil {
		panic(err)
	}
	fmt.Println(len(result.Results))
}

See the Go package reference for exported request and response types and the client reference notes for request-specific behavior. The project's intended scope and compatibility boundaries are in VISION.md.

Development

Go 1.26.6 is required.

go mod download
go build ./...
make lint test coverage

Authenticated end-to-end tests are optional; see development notes.

License

MIT. See LICENSE.