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/batchAuthentication
This endpoint requires authentication via a JWT Bearer token.
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/jsonParameters
Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
queries | string[] | Yes | Array of addresses to geocode (1 to 100 items) |
Constraints
| Constraint | Value |
|---|---|
| Minimum items | 1 |
| Maximum items | 100 |
| Max size per query | 500 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.jsonResponse
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
| Field | Type | Description |
|---|---|---|
results | array | Array of results (same order as requests) |
total | number | Total number of addresses processed |
successful | number | Number of successful geocodes |
failed | number | Number of failures |
Each Result
| Field | Type | Description |
|---|---|---|
query | string | Original requested address |
status | string | "ok", "not_found", or "error" |
lat | number | Latitude (if status = "ok") |
lon | number | Longitude (if status = "ok") |
display_name | string | Formatted address (if status = "ok") |
country | string | Country (if status = "ok") |
city | string | City (if status = "ok") |
confidence | number | Confidence score 0-1 (if status = "ok") |
error | string | Error message (if status = "error") |
status Values
| Status | Meaning |
|---|---|
ok | Address found successfully |
not_found | No result for this address |
error | Processing error |
HTTP Codes
| Code | Status | Description |
|---|---|---|
200 | OK | Request processed (some results may be errors) |
400 | Bad Request | Invalid body, empty or too large array |
401 | Unauthorized | Missing or invalid JWT token |
429 | Too Many Requests | Request limit exceeded |
503 | Service Unavailable | Service 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
doneBest 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 1Result Order
Results are returned in the same order as requests. You can easily associate each result with its original request.
Limits
| Limit | Value |
|---|---|
| Addresses per batch | 100 maximum |
| Size per address | 500 characters |
| Counting | 1 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