GET /v1/geocoding/autocomplete

Provides real-time search suggestions during user input. This endpoint is optimized for speed and returns lightweight results, ideal for search fields.

Designed for speed: Autocomplete is optimized for LLMs and AI applications that need to quickly identify a place (country, city, monument) without superfluous details. It does not return hotels or restaurants.

Endpoint

GET https://places.gotravelyzer.com/v1/geocoding/autocomplete

Authentication

This endpoint requires authentication via a JWT Bearer token.

Authorization: Bearer YOUR_JWT_TOKEN

Parameters

Query Parameters

Parameter	Type	Required	Description	Default
`q`	`string`	Yes	Partial search term	-
`limit`	`integer`	No	Number of suggestions (1-10)	`5`

The parameter is called q (not query) for this route, to keep URLs concise.

Requests

Basic Request

curl "https://places.gotravelyzer.com/v1/geocoding/autocomplete?q=Par" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

With Custom Limit

curl "https://places.gotravelyzer.com/v1/geocoding/autocomplete?q=Par&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Search for a Monument

curl "https://places.gotravelyzer.com/v1/geocoding/autocomplete?q=Eiffel%20Tow" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Search for an Airport

curl "https://places.gotravelyzer.com/v1/geocoding/autocomplete?q=CDG" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

Success Example (200 OK)

[
  {
    "display_name": "Paris, Île-de-France, France",
    "lat": 48.8588897,
    "lon": 2.3200410,
    "country": "France",
    "city": "Paris",
    "type": "city"
  },
  {
    "display_name": "Paris, Texas, United States",
    "lat": 33.6617962,
    "lon": -95.5555199,
    "country": "United States",
    "city": "Paris",
    "type": "city"
  },
  {
    "display_name": "Parc des Princes, Paris, France",
    "lat": 48.8414356,
    "lon": 2.2530177,
    "country": "France",
    "city": "Paris",
    "type": "stadium"
  }
]

Autocomplete responses are lightweight to optimize speed. For complete information about a place, use the Forward Geocoding endpoint.

Response Fields

Field	Type	Description
`display_name`	`string`	Full name of the place to display
`lat`	`number`	Latitude in decimal degrees
`lon`	`number`	Longitude in decimal degrees
`country`	`string`	Country name
`city`	`string`	City name (if applicable)
`type`	`string`	Place type (city, town, village, stadium, airport, etc.)

HTTP Codes

Code	Status	Description
`200`	OK	Successful request (may return an empty array)
`400`	Bad Request	Missing or invalid `q` parameter
`401`	Unauthorized	Missing or invalid JWT token
`429`	Too Many Requests	Request limit exceeded
`502`	Bad Gateway	Service error
`503`	Service Unavailable	Service temporarily unavailable

Error Examples

400 Bad Request - Missing Parameter

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "q parameter is required"
}

Best Practices

Implement Debounce

Important: Don't make a request on every keystroke. Use a debounce of 250-300ms to avoid overloading the API.

# Simulating debounce with a script
# Only send the request 300ms after the last input
 
sleep 0.3  # Wait for debounce
curl "https://places.gotravelyzer.com/v1/geocoding/autocomplete?q=Paris" \
  -H "Authorization: Bearer $TOKEN"

Minimum Length

Don't send requests for strings that are too short:

Length	Recommended Action
1 character	Don't request
2 characters	Start requesting
3+ characters	Request normally

# Check length before calling the API
QUERY="Pa"
if [ ${#QUERY} -ge 2 ]; then
  curl "https://places.gotravelyzer.com/v1/geocoding/autocomplete?q=$QUERY" \
    -H "Authorization: Bearer $TOKEN"
fi

Client-Side Cache

Cache recent results to improve performance and reduce API calls:

Request	Action
`"Par"`	API request → Cache
`"Pari"`	API request → Cache
`"Par"` (again)	Use cache

Performance

The autocomplete endpoint is optimized for fast responses:

Metric	Target
Target response time	< 100ms
Average response size	< 2 KB

Tips for Optimizing Latency

Use debounce: Avoid unnecessary requests
Cache results: Reduce repeated calls
Limit results: limit=5 is sufficient for most cases
Cancel in-flight requests: If the user continues typing

Differences from Forward Geocoding

Aspect	Autocomplete	Forward Geocoding
Parameter	`q`	`query`
Optimization	Speed	Completeness
Returned fields	Limited	Complete
Max limit	10	50
Use case	Search fields	Full geocoding

Limits

Limit	Value
Maximum suggestions	10 per request
Minimum `q` length	1 character
Maximum `q` length	500 characters
Counting	1 request against quota

Technical Notes

Results are sorted by relevance
An empty array [] is returned if no suggestions match
Responses are optimized to be lightweight (fewer fields)
Target response time is under 100ms

Next Steps

Forward Geocoding

Get complete information about a place.

Reverse Geocoding

Convert coordinates to an address.

Batch Geocoding

Geocode multiple addresses at once.