The account API
Your Google Maps searches.
Inside your workflow.
Give your scripts and HTTP-capable agents access to the account you already use. The same balance, the same searches, with limits you control.
REST over HTTP. Works with suitable Claude Code, Codex and custom script setups. No hosted MCP server or automatic chat connector.
Estimate → submit → follow progress → export
Billing and owner actions stay in the web app.
Keep access narrow.
Choose read or write scopes, set a per-job search limit and a UTC-day cap, and give every tool its own expiring key.
Keep the balance shared.
Web and API jobs use your available searches. Reading the catalogue, estimating and exporting do not spend searches.
Keep control of purchases.
Keys cannot buy searches, change your plan or manage refills. Revocation blocks subsequent requests.
A safe first request
Connect your account before running work.
Sign in, create a named key in API access, then store it as GTME_API_KEY in your tool’s environment or secret store. The full secret is shown once. Never paste it into a shared prompt, source file or browser bundle.
# Store the secret in your tool's environment, outside prompts and source code.
# GTME_API_KEY is the key you create in your signed-in account.
export GTME_API_BASE="https://app.gtme.business/api/v1"
# Read your account balance and the limits on this key.
curl --fail-with-body "$GTME_API_BASE/account" \
-H "Authorization: Bearer $GTME_API_KEY"
# Public, authoritative workflow and endpoint schema.
curl --fail-with-body "$GTME_API_BASE/guide"
curl --fail-with-body "$GTME_API_BASE/openapi.json"This read-only example does not start a search. Follow the guide for exact request bodies and inspect the account’s environment before running work.
Before you spend searches
Build a deliberate search workflow.
Resolve and estimate.
Resolve city names through the catalogue. Review ambiguous locations. Estimate the complete configuration before submitting it.
Set a budget. Submit once.
Send an explicit
maxSearchesceiling and save anIdempotency-Key. Reuse that key and configuration after a lost response.Follow progress. Export.
Poll every 3–5 seconds, wait for a terminal state, then retrieve JSON or CSV. Honor
429 Retry-Afterrather than polling in a tight loop.
The working surface
From account balance to finished CSV.
Paths below are relative to https://app.gtme.business/api/v1. Protected requests use Authorization: Bearer with your key. Each request must satisfy its required scope.
| Method and path | Required scope | Purpose |
|---|---|---|
GET /account | account:read | Check your balance, account and key limits. |
POST /catalog/locations/resolve | searches:read | Resolve city names to supported search locations. |
POST /searches/estimate | searches:read | Validate a configuration and estimate the searches it needs. |
POST /searches | searches:write | Reserve searches and queue work within your explicit budget. |
GET /searches/:id | searches:read | Read your job’s status, progress and configuration. |
GET /searches/:id/results | searches:read | Retrieve filtered, paginated JSON results. |
GET /searches/:id/export | searches:read | Download matching results as a 15-column CSV. |
POST /searches/:id/stop | searches:write | Stop further work and preserve results already collected. |
Frequently asked questions
- Can I use this with Claude Code or Codex?
- Yes, in a setup that can make HTTP requests, such as a terminal-enabled coding agent. Give the tool the API guide and keep the secret key in its environment or secret store. This is a REST API, not a hosted MCP server or an automatically installed chat connector.
- Does a key only access my account?
- Yes. A key can read only its own account and searches, within the scopes you selected. It cannot access someone else’s data or call administration, billing, password or integration-secret actions.
- How do searches and limits work?
- API and web searches share your existing account balance. One term at one distinct location uses one search. Each API submission needs an explicit maxSearches ceiling, and is also limited by your key’s per-job limit and UTC-day cap. A successful query with zero matches still uses a search.
- What happens if a request times out?
- Save a unique Idempotency-Key before the first submission. Retry with that same key and configuration if the response is lost. An accepted replay returns the same search without another reservation. Changing the configuration with the same key returns a conflict.
- Can I stop a job or revoke access?
- Yes. A key with searches:write can stop its account’s job. Provider work already in progress may complete first. Revoke the key from the web app to block subsequent authentication and new work; revocation alone does not cancel searches already accepted.
- How do API keys interact with purchases and automatic refills?
- Keys cannot purchase packs, change plans or enable refills. They spend searches available under your account’s entitlements. If you separately enable automatic refills in billing, web or API usage can lower the shared balance and trigger your authorized pack purchase within its spending cap. Keep key usage limits and refill spending limits aligned.
Start with one tool and one named key.
Keep your searches in one account. Keep each tool’s permissions under control.
Open API access