goplaces lets OpenClaw query Google Places through a separate CLI. Start with one concrete task: confirm a full address, find relevant places, and interpret the returned JSON. This guide uses macOS or Linux with Homebrew already available. The actual execution environment must reach Google APIs and have a Google Cloud project with billing and Places API (New) enabled, plus an API key.
Check the skill and execution host
Open a terminal on the host for your target OpenClaw agent. Replace YOUR_AGENT_ID with its actual ID:
openclaw skills info goplaces --agent YOUR_AGENT_ID
openclaw skills check --agent YOUR_AGENT_ID
These commands inspect the selected Gateway's authoritative skill inventory. Check whether goplaces exists and is visible, and whether the missing requirement is the binary or an environment variable. With a remote Gateway configured, the inventory belongs to that Gateway. A command available on your laptop may still be missing from the agent's host.
Only if that agent lacks the skill, install ClawHub v1.0.0 on the host containing its workspace:
openclaw skills install @steipete/goplaces --version 1.0.0 --agent YOUR_AGENT_ID
If the bundled copy is already present, supply its dependencies. The skill provides instructions; the goplaces CLI and Google API key need separate setup.
Prepare the CLI and API key
The official repository has moved to openclaw/goplaces, and Homebrew now uses a Formula. Follow the current README:
brew install openclaw/tap/goplaces
goplaces --version
If you have the retired Cask installed, follow the current README's migration steps first. The commands and JSON here refer to CLI v0.4.11. That version is separate from ClawHub skill v1.0.0. Later fixes on the repository's main branch do not establish which release is installed locally.
In your Google Cloud project, enable billing and Places API (New), create an API key, restrict its API scope, and set quotas for your use. This initial place lookup does not need Routes API; enable that separately if you later use route or directions.
For the current terminal, replace the placeholder with your own key:
export GOOGLE_PLACES_API_KEY="YOUR_API_KEY"
For OpenClaw, also supply that variable to the environment that actually executes commands. For example, merge this fragment into the Gateway's private openclaw.json configuration:
{
skills: {
entries: {
goplaces: {
env: { GOOGLE_PLACES_API_KEY: "YOUR_API_KEY" }
}
}
}
}
Keep the key out of chat. An export in another terminal does not update an already running Gateway. skills.entries injects into the host agent run; a sandbox separately needs the binary, key and network access. Recheck dependencies and use a new session after setup.
Requests are billed according to the fields requested. --limit 5 is not a free allowance. This release requests ratings and opening hours in searches, so the cost cannot be inferred simply from receiving five results. A read-only task bounds the actions for this round; the key's actual permissions still depend on its Google Cloud restrictions.
Confirm the address and choose a query
Replace the address placeholder with a full address, keeping the city and country to avoid similarly named streets or districts:
goplaces resolve "YOUR_FULL_ADDRESS, CITY, COUNTRY" --limit 3 --json
resolve --json returns a candidate array. Compare each candidate's name, address and location.lat / location.lng with the intended location. If several addresses are plausible, choose one before continuing; the first result is not a confirmed address merely because it appears first.
For a name or category lookup, use a query such as:
goplaces search "cafe near YOUR_FULL_ADDRESS, CITY, COUNTRY" --limit 5 --json
To favor confirmed coordinates, provide --lat, --lng and --radius-m together to search. These define a location bias, which permits results outside the circle. Google may ignore that bias when the query explicitly names another location. Without a supplied location, the server's IP can also influence results.
If the task requires cafes inside a 1.5 km circle, use the CLI's nearby command. Replace LAT_FROM_RESOLVE and LNG_FROM_RESOLVE with the confirmed numeric coordinates:
goplaces nearby --lat LAT_FROM_RESOLVE --lng LNG_FROM_RESOLVE --radius-m 1500 --type cafe --limit 5 --json
nearby sends a location restriction. It does not accept the search options --open-now or --min-rating shown in other examples. Read the returned opening and rating fields, and request details when needed.
Interpret the JSON and finish the first lookup
search and nearby return an object containing results. These are CLI field names, rather than the raw Google response's places / id:
| Field | What to check |
|---|---|
place_id | Keep the original value for a details request. |
name, address, location | Check the place, city and coordinates against your task. |
rating, user_rating_count | Read the rating alongside the number of reviews; preserve missing values as unknown. |
open_now | true / false is the returned opening state; an absent field does not mean closed. |
business_status | Treat this separately from opening state; it appears only when Google returns it. |
next_page_token | Indicates another text-search page, rather than the total number of places in the city. |
To inspect one candidate, replace the placeholder with its returned place_id:
goplaces details "PLACE_ID_FROM_RESULTS" --json
This returns one place object, with fields such as hours, phone and website when supplied. Add --reviews or --photos only when needed, and do not fill absent fields with model guesses.
For text search, continue one page using the same query and the returned next_page_token:
goplaces search "cafe near YOUR_FULL_ADDRESS, CITY, COUNTRY" --limit 5 --page-token "TOKEN_FROM_PREVIOUS_SEARCH" --json
Keep the previous request's query, location and filter parameters unchanged when paging. If it used --lat, --lng, --radius-m, --type or other filters, repeat those same values. The example above has no such additional parameters.
Each request can add API usage. Five candidates, an exhausted page sequence, or empty results does not establish coverage of all local businesses. The initial task is complete when you have confirmed the address, interpreted relevant candidates, and identified unknown fields and whether the location is biased or restricted.
Hand the task to OpenClaw
Once a terminal lookup gives results you can check, use a prompt like this in OpenClaw, replacing the address and range:
Use the goplaces skill to find cafes near [full address, city, country].
Confirm the address candidate first and ask me to choose if it is ambiguous.
For this round, make at most one resolve call and one place query, with up to five candidates.
My range requirement is [favor nearby results / require results within 1500 m of the confirmed coordinates]. Use the CLI nearby command for the strict circle.
List place_id, name, address, coordinates, rating and review count, open_now, and business_status.
Preserve missing fields as unknown and identify the source as Google Maps.
Show the candidates first. Explain any additional details or pagination query before continuing.
Do not book, contact businesses, or describe the result as a complete local directory.
If the agent and terminal differ, compare the actual command, query text, coordinates and execution environment. For command not found, check that environment's PATH. For a missing key, check the Gateway or sandbox configuration. Preserve API permission, quota and network diagnostics instead of turning them into “no places nearby.” Main-branch fixes after v0.4.11 address response validation and CLI output; a successful exit alone is not proof of completeness, and --limit 0 is not a way to avoid sending a query.
Before using results in a website, map, long-term store or public republication, design for the Google Places display, attribution and storage requirements. JSON output does not remove those requirements.