Google Maps via Scavio (v2)

Search Google Maps for places, fetch enriched details for a single place, and read its reviews — all as structured JSON. Three endpoints, each 1 credit.

When to trigger

Use this skill when the user asks to:

• Find local businesses or places ("coffee shops near downtown Austin")
• Get a place's address, phone, hours, rating, or coordinates
• Read reviews for a business or place
• Build a local lead list or enrich places with map data

Setup

Get a free API key at https://scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

Endpoints

| Endpoint | Credits | Description | |---|---|---| | POST https://api.scavio.dev/api/v2/google/maps/search | 1 | Search places, returns a paginated list | | POST https://api.scavio.dev/api/v2/google/maps/place | 1 | Full details for one place | | POST https://api.scavio.dev/api/v2/google/maps/reviews | 1 | Paginated reviews for a place |

Authorization: Bearer $SCAVIO_API_KEY

Workflow

1. Search: call /maps/search with a query. Results are in local_results[], each with a place_id, data_id, title, rating, address, and gps_coordinates.
2. Localize: Maps uses ll (map center @lat,lng,zoomz), NOT gl, to decide where results come from. Pass a city center (e.g. @30.2672,-97.7431,12z) to focus a city. If you only have a country, pass gl and the API defaults ll to that country's center.
3. Place details: take a place_id (or data_cid) from search and call /maps/place for full info in place_results.
4. Reviews: take a data_id (or place_id) and call /maps/reviews. Page with next_page_token.

Maps Search Parameters

| Parameter | Type | Default | Description | |---|---|---|---| | query | string | required | Search query (1-500 chars) | | ll | string | -- | Map center @lat,lng,zoomz. Controls result location. Defaults to gl country center if omitted | | start | number | 0 | Result offset, multiple of 20 (0, 20, 40, ...; max 100) | | gl | string | -- | Geo country, ISO 3166-1 alpha-2 | | hl | string | -- | UI language, ISO 639-1 | | google_domain | string | google.com | Regional Google domain |

Place Details Parameters

| Parameter | Type | Default | Description | |---|---|---|---| | place_id | string | -- | Place ID (ChIJ...). One of place_id or data_cid required | | data_cid | string | -- | Numeric CID. One of place_id or data_cid required |

Reviews Parameters

| Parameter | Type | Default | Description | |---|---|---|---| | data_id | string | -- | Data ID (0xHEX:0xHEX). One of data_id or place_id required | | place_id | string | -- | Place ID (ChIJ...). One of data_id or place_id required | | num | number | -- | Reviews per page (1-20) | | sort_by | string | -- | relevance, newest, highest_rating, lowest_rating | | next_page_token | string | -- | Pagination cursor from a prior response | | hl | string | -- | UI language | | gl | string | -- | Geo country | | google_domain | string | google.com | Regional Google domain |

Example

import os, requests

BASE = "https://api.scavio.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['SCAVIO_API_KEY']}"}

# 1. Search places, focused on Austin
search = requests.post(f"{BASE}/api/v2/google/maps/search", headers=HEADERS,
    json={"query": "coffee shops", "ll": "@30.2672,-97.7431,12z"}).json()

place = search["local_results"][0]
print(place["title"], place.get("rating"), place.get("address"))

# 2. Full details for that place
detail = requests.post(f"{BASE}/api/v2/google/maps/place", headers=HEADERS,
    json={"place_id": place["place_id"]}).json()
print(detail["place_results"].get("phone"), detail["place_results"].get("hours"))

# 3. Newest reviews
reviews = requests.post(f"{BASE}/api/v2/google/maps/reviews", headers=HEADERS,
    json={"data_id": place["data_id"], "sort_by": "newest", "num": 10}).json()
for r in reviews["reviews"]:
    print(r.get("rating"), r.get("snippet"))

Responses

Search returns local_results[]; place returns place_results; reviews returns place_info, topics[], reviews[], and pagination. Each also includes response_time, credits_used, credits_remaining, and cached.

{
  "local_results": [
    {
      "position": 1,
      "title": "Example Coffee",
      "place_id": "ChIJLSsVbGBZwokRR0LlGBSvMOI",
      "data_id": "0x89c259606c152b2d:0xe230af1b18e542a7",
      "rating": 4.6,
      "reviews": 1284,
      "address": "123 Main St, Austin, TX",
      "gps_coordinates": { "latitude": 30.27, "longitude": -97.74 }
    }
  ],
  "response_time": 1103,
  "credits_used": 1,
  "credits_remaining": 998,
  "cached": false
}

Guardrails

• Each call costs 1 credit. Inform the user before paginating through many pages.
• Never fabricate place names, ratings, addresses, or review text. Only return API data.
• Maps localizes by ll (map center), not gl. To search a specific city, pass its center.
• place needs a place_id/data_cid and reviews needs a data_id/place_id — always run /maps/search first to obtain them.

Failure handling

• 400 means an invalid parameter (e.g. missing place identifier) — fix and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 429 means rate or usage limit exceeded. Wait before retrying. See https://scavio.dev/docs/rate-limits.
• 502 / 503 mean upstream is temporarily unavailable. Wait a few seconds before retrying.
• If search returns no results, suggest a broader query or a different ll/gl.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.