goplaces

goplaces is a Go module and command-line tool designed for interacting with the Google Places API (New) and selected Routes API workflows.

It is intended for developers who want to:

• Perform text search, nearby search, autocomplete, place details, and photo retrieval.
• Use place data in shell automation or terminal workflows.
• Embed Google Places functionality into Go applications without manually managing field masks, request payloads, pagination, or output formatting.
• Perform route-aware place searches using the Routes API.

Key characteristics:

• Go Library: Provides typed requests/responses, validation, and sanitized error handling via github.com/steipete/goplaces.
• CLI Tool: Provides argument parsing, human-readable output, and machine-readable JSON output via the goplaces binary.

When using autocomplete, keep the following in mind:

• Billing Consistency: Always use a SessionToken to ensure that billing remains consistent when transitioning from an autocomplete request to a details request.
• Result Limits: The Limit parameter is applied client-side after the API response is received, rather than strictly on the server side.

When requesting photo media:

• The response always returns a direct URL (skipping redirects) to facilitate easy downloading.
• If providing dimensions (max-width or max-height), the value must be an integer between 1 and 4800.

When using route search features in goplaces:

• API Requirement: You must have the Google Routes API enabled in your Google Cloud project.
• Waypoint Sampling: Waypoints are sampled evenly along the route polyline.
• Coordinate Handling:
  • Longitude interpolation follows the short crossing of the international date line.
  • Malformed or out-of-range polyline coordinates are rejected before place searches are attempted.

When using the Go client, be aware of the following mapping and validation rules for search parameters:

• Types: Filters.Types maps to Google's singular includedType. Only the first value in the slice is sent to the API.
• Price Levels: Use integers ranging from 0 (free) to 4 (very expensive).
• Validation: Coordinates, radii, and minimum ratings must be finite numbers. Invalid values will trigger validation errors before any API calls are made.
• Media: PhotoMediaRequest requires either MaxWidthPx or MaxHeightPx. Each dimension must be between 1 and 4800.

The client restricts redirects to the original origin (same scheme, hostname, and port). Redirects to a different origin are rejected to ensure API keys remain scoped to the configured endpoint.

• Custom Hosts: If you are using a different host, configure an endpoint override directly.
• Custom Redirect Logic: You can provide a custom HTTPClient.CheckRedirect to control or stop redirects manually.

To ensure your integrations or scripts do not break during updates, note that goplaces guarantees stability for the following surfaces:

1. Go Library: Exported identifiers and behavior in the github.com/steipete/goplaces package.
2. CLI: Command names, documented flags, environment variables, and exit-code classes.
3. Data Formats: JSON field names and response shapes emitted when using the --json flag.
4. Installation: Documented install commands and release artifact names.

Note: Human-readable text layout (colors, spacing, wording) is not considered a stable API and may change without notice.

Once the main branch is updated with the release date in CHANGELOG.md and a signed annotated vX.Y.Z tag has been pushed, you can create a GitHub draft. This process rebuilds the project from a fresh official-remote clone pinned to the verified tag.

Run the following command:

scripts/release-local draft vX.Y.Z

Expected Assets: The draft must contain exactly seven assets:

• Darwin amd64 and arm64 archives
• Linux amd64 and arm64 archives
• Windows amd64 and arm64 archives
• goplaces_checksums.txt

End-to-end (e2e) tests are optional and interact with live Google services, meaning they will consume API quota or incur billing charges. To run them, you must provide a valid Google Places API key via the GOOGLE_PLACES_API_KEY environment variable.

export GOOGLE_PLACES_API_KEY="..."
make e2e