Cross-feature queries

By the end of this guide, you'll understand how Plaza chains multiple operations into a single request and why that matters.

The problem

Say you want to find every hospital reachable by car within 15 minutes of a street address. With most geo APIs, you'd do this:

1. Geocode the address (API call #1)
2. Calculate a 15-minute driving isochrone from those coordinates (API call #2)
3. Search for hospitals inside that polygon (API call #3)
4. Write client-side glue code to pass results between steps

Three round trips, three bills, and a bunch of plumbing. If any step fails, you retry the whole chain.

How Plaza handles it

Plaza runs the whole pipeline server-side in a single database transaction. The geocode result becomes the center of the isochrone calculation, which becomes the spatial filter for the search. One HTTP call, one response.

There's no network overhead between steps because nothing leaves Postgres. A geocode-to-isochrone-to-search pipeline typically completes in 200-500ms, compared to 1-3 seconds when chaining separate calls from a client.

Cross-query endpoints

Geocode + nearby search

Find places near an address without geocoding separately:

curl "https://plaza.fyi/api/v1/nearby?address=Shibuya+Station,+Tokyo&radius=300&tags=amenity%3Dcafe" \
  -H "x-api-key: pk_live_YOUR_KEY"

Pass address instead of lat/lng. Plaza geocodes internally and searches around the result.

Isochrone + search

Find all pharmacies within a 10-minute walk:

curl "https://plaza.fyi/api/v1/isochrone?lat=40.7128&lng=-74.0060&time=600&mode=foot&search=amenity%3Dpharmacy" \
  -H "x-api-key: pk_live_YOUR_KEY"

The response includes both the isochrone polygon and every matching feature inside it. One request.

Search along a route

Find coffee shops along your commute:

curl -X POST "https://plaza.fyi/api/v1/route" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {"lat": 48.8566, "lng": 2.3522},
    "destination": {"lat": 48.8849, "lng": 2.3350},
    "search_along": {"tags": "amenity=cafe", "buffer_m": 200}
  }'

This calculates the route, buffers it by 200 meters, and returns every cafe within that corridor alongside the route geometry.

Nearest to multiple origins

Find the 3 closest coffee shops to each of your office locations:

curl -X POST "https://plaza.fyi/api/v1/matrix" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origins": [
      {"lat": 51.5074, "lng": -0.1278},
      {"lat": 51.5155, "lng": -0.1419}
    ],
    "destinations": "nearest:amenity=cafe:3",
    "mode": "foot"
  }'

Plaza finds the 3 nearest cafes to each origin, then calculates walking distances between every pair.

Real example: hospitals near an address

Here's the hospital scenario from above, done both ways.

The three-call way (any geo API)

import requests

headers = {"x-api-key": "pk_live_YOUR_KEY"}

# Call 1: geocode
geo = requests.get("https://plaza.fyi/api/v1/geocode",
    params={"q": "Alexanderplatz 1, Berlin"}, headers=headers).json()
lat, lng = geo["results"][0]["lat"], geo["results"][0]["lng"]

# Call 2: isochrone
iso = requests.get("https://plaza.fyi/api/v1/isochrone",
    params={"lat": lat, "lng": lng, "time": 900, "mode": "auto"},
    headers=headers).json()

# Call 3: search within the isochrone area
hospitals = requests.get("https://plaza.fyi/api/v1/nearby",
    params={"lat": lat, "lng": lng, "radius": 5000, "tags": "amenity=hospital"},
    headers=headers).json()

The one-call way (Plaza cross-feature)

import requests

resp = requests.get(
    "https://plaza.fyi/api/v1/isochrone",
    params={
        "lat": 52.5219, "lng": 13.4132,
        "time": 900, "mode": "auto",
        "search": "amenity=hospital"
    },
    headers={"x-api-key": "pk_live_YOUR_KEY"}
)
# Done. Results include only hospitals within 15 min drive time.

Comparison with Google Maps

Here's the same query with Google's APIs:

import googlemaps
gmaps = googlemaps.Client(key="GOOGLE_KEY")

# Call 1: geocode
geo = gmaps.geocode("Alexanderplatz 1, Berlin")
loc = geo[0]["geometry"]["location"]

# Call 2: Google doesn't have isochrones at all.
# You'd need to call Distance Matrix for every candidate hospital
# to check which ones are within 15 minutes.

# Call 3: places nearby (radius only, not travel time)
hospitals = gmaps.places_nearby(
    location=(loc["lat"], loc["lng"]),
    radius=5000,
    type="hospital"
)
# Still no travel-time filtering. You'd need another N calls to the
# Distance Matrix to check each hospital's drive time.

Google doesn't offer isochrones, so you literally can't replicate this query without building your own travel-time filtering. With Plaza, it's a query parameter.

When to use cross-feature queries

Use them when you actually need the chaining. If you already have coordinates and just want a nearby search, the simple /nearby endpoint is fine. Cross-feature queries are heavier on the server because they do more work per request.

The sweet spot: any workflow where you'd otherwise need to geocode an address, then compute a spatial region, then search within it. That's 3 round trips collapsed into 1.