Examples

Real conversations, with the actual tool calls the assistant would make behind the scenes. Drop any of these prompts in and the flow should match.

Geocoding

Address to coordinates

You: Geocode "10 Downing Street, London"

The assistant calls geocode({ query: "10 Downing Street, London" }) and answers:

10 Downing Street, London, SW1A 2AA, United Kingdom
Coordinates: 51.5034, -0.1276

Coordinates to address

You: What's at 40.7484, -73.9857?

reverse_geocode({ lat: 40.7484, lng: -73.9857 }) →

Empire State Building, 350 5th Avenue, New York, NY 10118, United States

Place search

You: Find coffee shops near the Eiffel Tower

autocomplete({ query: "coffee Eiffel Tower Paris" }) returns a list of matches with their coordinates.

Map styles

Create one

You: Create a dark map style called "Midnight" for my app

create_style({ name: "Midnight", preset: "dark" }) — the assistant confirms with the style ID and preview URL.

Edit with natural language

You: Make the water deeper blue and hide road labels on my "Midnight" style

modify_style_ai({ style_id: "...", instructions: "Make water color deeper blue (#0a1628) and hide all road labels" }) — the assistant reports what changed.

Brand-matched styles

You: Create a map style that matches the Notion website brand

brand_style({ website_url: "https://notion.so" }) returns a style with Notion's palette applied to land, water, roads, labels, etc.

GIS export

For QGIS

You: I need to load my city-streets tiles into QGIS

get_tile_url({ style_slug: "city-streets" }) →

Tile URL: https://tiles.maps.guru/v1/planet-vector/{z}/{x}/{y}.pbf?key=mapx_xxx

QGIS connection URI (paste into "Add XYZ Tiles"):
type=xyz&url=https://tiles.maps.guru/v1/planet-vector/{z}/{x}/{y}.pbf?key=mapx_xxx&zmax=14&zmin=0

Style URL: https://maps.guru/api/v1/styles/public/city-streets/style.json?key=mapx_xxx

Dataset to GeoJSON

You: Export my earthquake-data dataset as GeoJSON for analysis in Python

get_dataset_geojson({ dataset_id: "..." }) returns a URL you can read straight into geopandas:

import geopandas as gpd
gdf = gpd.read_file("https://maps.guru/api/v1/datasets/abc123/geojson?key=mapx_xxx")

Static maps for a report

You: Generate map images of Tokyo, Seoul, and Singapore at zoom 11 for my quarterly report

Three get_static_map calls, one per city. Images come back inline — drop them straight into the document.

Account and usage

Quota check

You: How many API calls have I used this month?

get_usage() →

This month's usage:
- Maps: 12,450 / 500,000 (2.5%)
- Geocoding: 3,200 / 100,000 (3.2%)
- Routing: 890 / 100,000 (0.9%)

Plan: Pro ($49/month)

List your styles

You: Show me all my map styles

list_styles() returns a table with names, presets, creation dates, and share status.

Multi-tool workflows

New project setup

You: I'm starting a new project. Create a light map style called "Project Atlas", share it publicly, and give me the tile URL for QGIS.

Three chained calls:

1. create_style({ name: "Project Atlas", preset: "light" }) — creates the style
2. share_style({ style_id: "..." }) — makes it public
3. get_tile_url({ style_slug: "project-atlas" }) — returns the QGIS-ready URI

All three results in one response.

Geocode and visualize

You: Geocode "Machu Picchu" and generate a static map centered on it

1. geocode({ query: "Machu Picchu" }) → (-13.1631, -72.5450)
2. get_static_map({ style_slug: "satellite", lat: -13.1631, lng: -72.5450, zoom: 14 })

The map renders inline.