Quickstart

This guide allows you to make your first API call in just a few minutes. Follow these steps to get the coordinates of a place.

Prerequisites

Before you begin, make sure you have:

A developer account on the Travelyzer Dashboard
Your API credentials (API Key and API Secret) — How to get them
cURL or a similar tool (Postman, Insomnia, HTTPie...)

Step 1: Verify Connection

Start by verifying that the API is accessible. The /health endpoint does not require authentication:

curl "https://places.gotravelyzer.com/health"

Expected response:

{
  "ok": true
}

If you get this response, the API is operational. You can proceed to the next step.

Step 2: Get a JWT Token

Exchange your credentials for a JWT token. This token will be used to authenticate all your requests.

curl -X POST "https://api2.gotravelyzer.com/api-clients/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "gck_your_api_key",
    "apiSecret": "gcs_your_api_secret"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-02-24T12:00:00.000Z",
  "clientId": "client_abc123"
}

Keep this token safe. It is valid for 1 hour by default. For a longer duration, add "expiresIn": "24h" in the body.

Step 3: First Geocoding Call

Use your token to search for the coordinates of Paris:

curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Paris" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

[
  {
    "place_id": 123456789,
    "display_name": "Paris, Île-de-France, France",
    "lat": 48.8588897,
    "lon": 2.3200410,
    "country": "France",
    "city": "Paris",
    "category": "boundary",
    "type": "administrative",
    "importance": 0.93,
    "boundingbox": [48.8155, 48.9021, 2.2241, 2.4697],
    "address": {
      "city": "Paris",
      "state": "Île-de-France",
      "country": "France",
      "country_code": "fr"
    },
    "confidence": 0.98
  }
]

Congratulations! You've just made your first call to the geocoding API.

Step 4: Understanding the Response

The API returns an array of results sorted by relevance. Here are the main fields:

Field	Type	Description
`place_id`	`number`	Unique identifier of the place
`display_name`	`string`	Full name with administrative hierarchy
`lat`	`number`	Latitude in decimal degrees (WGS84)
`lon`	`number`	Longitude in decimal degrees (WGS84)
`country`	`string`	Country name
`city`	`string`	City name (if applicable)
`category`	`string`	Main category of the place
`type`	`string`	Specific type of the place
`importance`	`number`	Relevance score (0 to 1)
`boundingbox`	`number[]`	Bounding area [south, north, west, east]
`address`	`object`	Detailed address components
`confidence`	`number`	Result confidence score (0 to 1)

Using the Coordinates

The lat and lon fields can be used directly with any mapping library:

Google Maps: new google.maps.LatLng(48.8588897, 2.3200410)
Leaflet: L.marker([48.8588897, 2.3200410])
Mapbox: [2.3200410, 48.8588897] (note: lon, lat)

Step 5: Practical Examples

Search for a Complete Address

curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=10%20Downing%20Street%20London" \
  -H "Authorization: Bearer YOUR_TOKEN"

Search for a Monument

curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Eiffel%20Tower%20Paris" \
  -H "Authorization: Bearer YOUR_TOKEN"

Search for an Airport

curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=CDG%20Airport" \
  -H "Authorization: Bearer YOUR_TOKEN"

Search for an Airport with City

curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=CDG%20Airport%20Paris" \
  -H "Authorization: Bearer YOUR_TOKEN"

Limit the Number of Results

By default, the API returns up to 5 results. Use the limit parameter to get more (maximum 50):

curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Berlin%20Germany&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 6: Reverse Geocoding

Convert GPS coordinates into an address with the /v1/geocoding/reverse endpoint:

curl "https://places.gotravelyzer.com/v1/geocoding/reverse?lat=48.8584&lon=2.2945" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "place_id": 987654321,
  "display_name": "Eiffel Tower, Avenue Anatole France, 75007 Paris, France",
  "lat": 48.8584,
  "lon": 2.2945,
  "country": "France",
  "city": "Paris",
  "category": "tourism",
  "type": "attraction",
  "address": {
    "house_number": "5",
    "road": "Avenue Anatole France",
    "suburb": "7th Arrondissement",
    "city": "Paris",
    "postcode": "75007",
    "country": "France",
    "country_code": "fr"
  },
  "confidence": 0.95
}

Step 7: Handling Errors

Expired Token (401)

If your token has expired, you will receive:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Token expired"
}

Solution: Request a new token via /api-clients/token.

Quota Exceeded (429)

If you exceed your request limit:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "retryAfter": 30
}

Solution: Wait the number of seconds indicated in retryAfter, then retry.

Missing Parameter (400)

If you forget a required parameter:

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

Solution: Make sure you have included all required parameters.

Complete Script

Here's a reusable bash script for geocoding:

#!/bin/bash
 
# Configuration
API_KEY="gck_your_api_key"
API_SECRET="gcs_your_api_secret"
QUERY="Eiffel Tower, Paris"
 
# 1. Get the token
echo "Getting token..."
TOKEN_RESPONSE=$(curl -s -X POST "https://api2.gotravelyzer.com/api-clients/token" \
  -H "Content-Type: application/json" \
  -d "{\"apiKey\": \"$API_KEY\", \"apiSecret\": \"$API_SECRET\"}")
 
TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.token')
 
if [ "$TOKEN" == "null" ]; then
  echo "Error: Unable to get token"
  echo $TOKEN_RESPONSE
  exit 1
fi
 
echo "Token obtained successfully!"
 
# 2. Make the geocoding request
echo "Searching for: $QUERY"
ENCODED_QUERY=$(echo "$QUERY" | jq -sRr @uri)
 
RESULT=$(curl -s "https://places.gotravelyzer.com/v1/geocoding/forward?query=$ENCODED_QUERY" \
  -H "Authorization: Bearer $TOKEN")
 
# 3. Display the result
echo "Result:"
echo $RESULT | jq '.[0] | {display_name, lat, lon, country, city}'

Summary

Endpoint	Method	Description
`/api-clients/token`	POST	Get a JWT token
`/v1/geocoding/forward`	GET	Address → Coordinates
`/v1/geocoding/reverse`	GET	Coordinates → Address
`/health`	GET	Check API status

Next Steps

Forward Geocoding

Complete documentation of the geocoding endpoint.

Rate Limits

Understand quotas and request limits.

Error Handling

All error codes and their solutions.