Batch Geocoding

Geocode multiple addresses in a single API request.

POST /v1/geocoding/batch

Geocodes up to 100 addresses in a single API request. Ideal for bulk data processing, CSV file imports, or batch address validation.

Endpoint

POST https://places.gotravelyzer.com/v1/geocoding/batch

Authentication

This endpoint requires authentication via a JWT Bearer token.

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Parameters

Request Body (JSON)

FieldTypeRequiredDescription
queriesstring[]YesArray of addresses to geocode (1 to 100 items)

Constraints

ConstraintValue
Minimum items1
Maximum items100
Max size per query500 characters

Counting: Each address in the batch counts as 1 request against your monthly quota. A batch of 50 addresses = 50 requests.


Requests

Basic Request

curl -X POST "https://places.gotravelyzer.com/v1/geocoding/batch" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "Eiffel Tower, Paris",
      "Big Ben, London",
      "Colosseum, Rome"
    ]
  }'

Request with More Addresses

curl -X POST "https://places.gotravelyzer.com/v1/geocoding/batch" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "Eiffel Tower, Paris, France",
      "Big Ben, Westminster, London, UK",
      "Colosseum, Rome, Italy",
      "Statue of Liberty, New York, USA",
      "Sydney Opera House, Australia",
      "Machu Picchu, Peru"
    ]
  }'

Request from a File

# Create a JSON file with addresses
cat > addresses.json << 'EOF'
{
  "queries": [
    "10 Downing Street, London",
    "1600 Pennsylvania Avenue, Washington DC",
    "Champs-Élysées, Paris"
  ]
}
EOF
 
# Send the request
curl -X POST "https://places.gotravelyzer.com/v1/geocoding/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @addresses.json

Response

Success Example (200 OK)

{
  "results": [
    {
      "query": "Eiffel Tower, Paris",
      "status": "ok",
      "lat": 48.8582599,
      "lon": 2.2945006,
      "display_name": "Eiffel Tower, 5, Avenue Anatole France, Paris, 75007, France",
      "country": "France",
      "city": "Paris",
      "confidence": 0.95
    },
    {
      "query": "Big Ben, London",
      "status": "ok",
      "lat": 51.5007292,
      "lon": -0.1246254,
      "display_name": "Big Ben, Westminster, London, SW1A 0AA, UK",
      "country": "United Kingdom",
      "city": "London",
      "confidence": 0.93
    },
    {
      "query": "Nonexistent address xyz123",
      "status": "not_found"
    },
    {
      "query": "Colosseum, Rome",
      "status": "ok",
      "lat": 41.8902102,
      "lon": 12.4922309,
      "display_name": "Colosseum, Piazza del Colosseo, Rome, Italy",
      "country": "Italy",
      "city": "Rome",
      "confidence": 0.94
    }
  ],
  "total": 4,
  "successful": 3,
  "failed": 1
}

Batch always returns a 200 OK code even if some addresses were not found. Check the status field of each result.

Response Fields

Global Response

FieldTypeDescription
resultsarrayArray of results (same order as requests)
totalnumberTotal number of addresses processed
successfulnumberNumber of successful geocodes
failednumberNumber of failures

Each Result

FieldTypeDescription
querystringOriginal requested address
statusstring"ok", "not_found", or "error"
latnumberLatitude (if status = "ok")
lonnumberLongitude (if status = "ok")
display_namestringFormatted address (if status = "ok")
countrystringCountry (if status = "ok")
citystringCity (if status = "ok")
confidencenumberConfidence score 0-1 (if status = "ok")
errorstringError message (if status = "error")

status Values

StatusMeaning
okAddress found successfully
not_foundNo result for this address
errorProcessing error

HTTP Codes

CodeStatusDescription
200OKRequest processed (some results may be errors)
400Bad RequestInvalid body, empty or too large array
401UnauthorizedMissing or invalid JWT token
429Too Many RequestsRequest limit exceeded
503Service UnavailableService temporarily unavailable

Error Examples

400 Bad Request - Array Too Large

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "queries array must contain between 1 and 100 items"
}

400 Bad Request - Invalid Body

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "queries must be an array of strings"
}

400 Bad Request - Empty Array

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "queries array cannot be empty"
}

Use Cases

CSV Data Import

Geocode a CSV file containing addresses:

#!/bin/bash
 
TOKEN="your_token"
 
# Read addresses from CSV (column 1)
ADDRESSES=$(cut -d',' -f1 addresses.csv | tail -n +2 | head -100)
 
# Build JSON
JSON='{"queries": ['
FIRST=true
while IFS= read -r addr; do
  if [ "$FIRST" = true ]; then
    FIRST=false
  else
    JSON+=','
  fi
  # Escape quotes
  ESCAPED=$(echo "$addr" | sed 's/"/\\"/g')
  JSON+="\"$ESCAPED\""
done <<< "$ADDRESSES"
JSON+=']}'
 
# Send request
curl -X POST "https://places.gotravelyzer.com/v1/geocoding/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$JSON"

Address Validation

Check which addresses are valid in a list:

# Send addresses
RESULT=$(curl -s -X POST "https://places.gotravelyzer.com/v1/geocoding/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "10 Downing Street, London",
      "Invalid address 12345",
      "1600 Pennsylvania Avenue, Washington"
    ]
  }')
 
# Display statistics
echo "Total: $(echo $RESULT | jq '.total')"
echo "Valid: $(echo $RESULT | jq '.successful')"
echo "Invalid: $(echo $RESULT | jq '.failed')"
 
# List invalid addresses
echo "Addresses not found:"
echo $RESULT | jq -r '.results[] | select(.status != "ok") | .query'

High Volume Processing

For more than 100 addresses, process in batches:

#!/bin/bash
 
TOKEN="your_token"
BATCH_SIZE=100
 
# File with all addresses (one per line)
ADDRESSES_FILE="all_addresses.txt"
TOTAL_LINES=$(wc -l < "$ADDRESSES_FILE")
 
echo "Processing $TOTAL_LINES addresses in batches of $BATCH_SIZE"
 
# Process in batches
for ((i=0; i<TOTAL_LINES; i+=BATCH_SIZE)); do
  echo "Batch $((i/BATCH_SIZE + 1)): lines $((i+1)) to $((i+BATCH_SIZE))"
 
  # Extract batch
  BATCH=$(sed -n "$((i+1)),$((i+BATCH_SIZE))p" "$ADDRESSES_FILE")
 
  # Build JSON
  JSON='{"queries": ['
  FIRST=true
  while IFS= read -r addr; do
    [ -z "$addr" ] && continue
    if [ "$FIRST" = true ]; then FIRST=false; else JSON+=','; fi
    JSON+="\"$(echo "$addr" | sed 's/"/\\"/g')\""
  done <<< "$BATCH"
  JSON+=']}'
 
  # Send and save
  curl -s -X POST "https://places.gotravelyzer.com/v1/geocoding/batch" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "$JSON" >> results.jsonl
 
  # Pause to respect rate limits
  sleep 1
done

Best Practices

Handling Partial Failures

Always check the status of each result:

# Filter successful results
curl -s -X POST "...batch" -d '...' | jq '.results[] | select(.status == "ok")'
 
# Filter failures
curl -s -X POST "...batch" -d '...' | jq '.results[] | select(.status != "ok")'

Pause Between Batches

For high volumes, add a pause between requests:

# Wait 1 second between each batch of 100
sleep 1

Result Order

Results are returned in the same order as requests. You can easily associate each result with its original request.


Limits

LimitValue
Addresses per batch100 maximum
Size per address500 characters
Counting1 request per address

Technical Notes

  • Results are returned in the same order as requests
  • Requests are processed in parallel to optimize performance
  • A delay between batches is recommended for high volumes
  • Failed requests are not automatically retried

Next Steps