Batch Geocoding

Endpoint

POST /api/v1/geocode/batch

Up to 1,000 addresses per request. Returns one GeoJSON FeatureCollection per input address, in order.

Request body

{
  "addresses": [
    "1600 Pennsylvania Ave NW, Washington DC",
    "350 Fifth Avenue, New York NY",
    "1 Infinite Loop, Cupertino CA"
  ]
}

Options

Field	Type	Default	Description
addresses	string[]	—	Required. Array of address strings (1–1,000).

Response

{
  "results": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": { "type": "Point", "coordinates": [-77.0365, 38.8977] },
          "properties": {
            "osm_id": 238241022,
            "osm_type": "way",
            "display_name": "The White House, 1600 Pennsylvania Avenue NW, Washington, DC 20500",
            "country_code": "us",
            "score": 0.98,
            "source": "structured"
          }
        }
      ]
    },
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": { "type": "Point", "coordinates": [-73.9857, 40.7484] },
          "properties": {
            "osm_id": 34633854,
            "osm_type": "way",
            "display_name": "Empire State Building, 350 Fifth Avenue, New York, NY 10118",
            "country_code": "us",
            "score": 0.96,
            "source": "structured"
          }
        }
      ]
    },
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": { "type": "Point", "coordinates": [-122.0308, 37.3318] },
          "properties": {
            "osm_id": 26474008,
            "osm_type": "way",
            "display_name": "1 Infinite Loop, Cupertino, CA 95014",
            "country_code": "us",
            "score": 0.95,
            "source": "structured"
          }
        }
      ]
    }
  ],
  "count": 3
}

Unmatched addresses return an empty FeatureCollection ("features": []). The response always matches the input array length.

curl example

curl -X POST "https://plaza.fyi/api/v1/geocode/batch" \
  -H "x-api-key: $PLAZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "10 Downing Street, London",
      "1600 Pennsylvania Ave NW, Washington DC",
      "Champs-Élysées 101, Paris"
    ]
  }'

SDK examples

TypeScript

import Plaza from "@plazafyi/sdk";

const client = new Plaza();

const results = await client.v1.geocode.batch({
  addresses: [
    "350 Fifth Avenue, New York NY",
    "233 S Wacker Dr, Chicago IL",
    "600 Montgomery St, San Francisco CA",
  ],
});

for (const [i, fc] of results.results.entries()) {
  if (fc.features.length > 0) {
    const [lng, lat] = fc.features[0].geometry.coordinates;
    console.log(`Address ${i}: ${lat}, ${lng}`);
  } else {
    console.log(`Address ${i}: no match`);
  }
}

Python

import plaza
import csv

client = plaza.Client()

# Read addresses from a CSV
with open("customers.csv") as f:
    reader = csv.DictReader(f)
    addresses = [row["address"] for row in reader]

# Process in chunks of 1000
for i in range(0, len(addresses), 1000):
    chunk = addresses[i : i + 1000]
    results = client.v1.geocode.batch(addresses=chunk)

    for j, fc in enumerate(results.results):
        if fc.features:
            coords = fc.features[0].geometry.coordinates
            print(f"{chunk[j]} -> {coords[1]}, {coords[0]}")
        else:
            print(f"{chunk[j]} -> NOT FOUND")

Go

results, err := client.V1.Geocode.Batch(ctx, plaza.V1GeocodeBatchParams{
    Addresses: plaza.F([]string{
        "350 Fifth Avenue, New York NY",
        "233 S Wacker Dr, Chicago IL",
    }),
})
if err != nil {
    panic(err)
}

for i, fc := range results.Results {
    if len(fc.Features) > 0 {
        coords := fc.Features[0].Geometry.Coordinates
        fmt.Printf("Address %d: %f, %f\n", i, coords[1], coords[0])
    }
}

Use cases

• CSV import — Chunk customer addresses, store locations, or delivery points into groups of 1,000 and geocode each chunk.
• Address normalization — Geocode messy user-entered addresses to get a standardized display_name plus coordinates.
• Validation — Check score on each result. Below 0.7 likely means typos or incomplete data; flag for manual review.

Billing

Each address counts as one API call. A batch of 500 = 500 calls. No discount or surcharge — batching reduces HTTP overhead only.

Limits

• Max 1,000 addresses per request. Chunk larger datasets across multiple requests.
• 60-second timeout. Batches of 1,000 typically complete in 2–5s. Reduce chunk size if you hit timeouts.
• Rate limits still apply. A batch of 1,000 counts as 1,000 against your per-minute limit. Free tier (10 req/min) users should batch slowly or upgrade.