Google Maps via Scavio (v2)

Search Google Maps for places, fetch enriched details for a single place, read its reviews, and track where a business ranks across a geographic grid of points — all as structured JSON. Four endpoints on the v2 engine.

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
• Track where a business ranks in Google Maps local results across an area (a local-SEO geo-grid)

Setup

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

export SCAVIO_API_KEY=sk_live_your_key

If you do not have a key yet

An agent running this skill without SCAVIO_API_KEY set will get 401 on every call below. The whole path from nothing to a working key is self-serve:

1. Sign up at dashboard.scavio.dev - email or Google, no card required.
2. A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
3. A new account starts with 50 credits. Endpoints in this skill cost 1 credit each unless the table below says otherwise.

When the balance runs out the API answers 402 with a JSON body carrying billing_url. Topping up needs no code change - the same key keeps working. The smallest purchase is 2,500 credits for $25, and monthly plans work out cheaper per credit if the usage is steady rather than one-off.

Endpoints

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

Place Details Parameters

Reviews Parameters

Geo-Grid Rank Tracking Parameters

/maps/geo-grid tracks where one business ranks in the Google Maps local pack across an N×N lattice of points around a center — the classic local-SEO geo-grid. It searches query at every point and reports the target business's rank there, plus an aggregate summary (average, best, worst rank and coverage). Provide target_place_id and/or target_name.

Credits: billed per grid point — an N×N grid costs N² credits (9 for grid_size=3, 25 for 5, 49 for 7). Any point that returns no data is not charged.

Example

import requests

BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {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"))

# 4. Geo-grid: where does a business rank across a 3x3 grid? (9 credits)
grid = requests.post(f"{BASE}/api/v2/google/maps/geo-grid", headers=HEADERS,
    json={
        "query": "coffee shop",
        "target_name": "Starbucks",
        "center": {"lat": 40.7128, "lng": -74.006},
        "grid_size": 3,
        "radius_km": 2,
    }).json()
s = grid["data"]["summary"]
print(s["points_found"], "of", s["points_total"], "points rank; avg rank", s["avg_rank"])
for point in grid["data"]["grid"]:
    print(point["lat"], point["lng"], point["rank"])

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. Geo-grid wraps its payload in data: data.grid[] (each point with lat, lng, rank, found) and data.summary (points_total, points_found, avg_rank, best_rank, worst_rank, found_share).

{
  "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

• Search, place and reviews each cost 1 credit; geo-grid costs N² credits for an N×N grid (9 / 25 / 49). Inform the user before paginating through many pages or running a large grid.
• 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 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.