GET /v1/geocoding/forward

Converts a place name (country, city, monument) into geographic coordinates (latitude/longitude). This is the main endpoint for quickly identifying a location.

Optimized for LLMs: This API is designed to quickly find geographic places (countries, cities, monuments), not to search for hotels, restaurants, or precise addresses. It prioritizes speed over granular precision.

Endpoint

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

Authentication

This endpoint requires authentication via a JWT Bearer token.

Authorization: Bearer YOUR_JWT_TOKEN

Parameters

Query Parameters

Parameter	Type	Required	Description	Default
`query`	`string`	Yes	Search term (address, place, POI, coordinates)	-
`limit`	`integer`	No	Number of results to return (1-50)	`5`

`query` Parameter Constraints

Constraint	Value
Minimum length	1 character
Maximum length	500 characters
Encoding	UTF-8, URL encoded

Requests

Basic Request

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

With Result Limit

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

Search for a Complete Address

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

Search for a Monument

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

Search for an Airport

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

Response

Success Example (200 OK)

[
  {
    "place_id": 2681977,
    "display_name": "Eiffel Tower, Avenue Anatole France, Paris 7e Arrondissement, Paris, Île-de-France, 75007, France",
    "lat": 48.8582599,
    "lon": 2.2945006,
    "country": "France",
    "city": "Paris",
    "category": "tourism",
    "type": "attraction",
    "importance": 0.85,
    "boundingbox": [48.8574753, 48.8590453, 2.2933119, 2.2956897],
    "address": {
      "house_number": "5",
      "road": "Avenue Anatole France",
      "suburb": "Paris 7e Arrondissement",
      "city": "Paris",
      "state": "Île-de-France",
      "postcode": "75007",
      "country": "France",
      "country_code": "fr"
    },
    "confidence": 0.95
  }
]

Response Fields

Field	Type	Description
`place_id`	`number`	Unique identifier of the place
`display_name`	`string`	Full formatted 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)

`boundingbox` Field Detail

The boundingbox array contains 4 coordinates in decimal degrees:

Index	Description	Example
`[0]`	South latitude (minimum)	`48.8574753`
`[1]`	North latitude (maximum)	`48.8590453`
`[2]`	West longitude (minimum)	`2.2933119`
`[3]`	East longitude (maximum)	`2.2956897`

`address` Field Detail

Available fields vary depending on the type and location of the place:

Field	Description	Example
`house_number`	Street number	`"5"`
`road`	Street name	`"Avenue Anatole France"`
`suburb`	District/Suburb	`"Paris 7e Arrondissement"`
`city`	City	`"Paris"`
`county`	County/Department	`"Greater London"`
`state`	State/Region	`"Île-de-France"`
`postcode`	Postal code	`"75007"`
`country`	Country	`"France"`
`country_code`	ISO 3166-1 alpha-2 code	`"fr"`

`category` and `type` Values

Category	Common Types	Description
`boundary`	`administrative`, `country`, `state`	Administrative boundaries (countries, regions)
`place`	`city`, `town`, `village`, `country`	Inhabited places and countries
`tourism`	`attraction`, `monument`, `viewpoint`	Major tourist sites
`aeroway`	`aerodrome`, `terminal`	Airports
`railway`	`station`	Major train stations

The API primarily returns geographic places (countries, cities, monuments, airports). It is not designed to return businesses, hotels, or restaurants.

HTTP Codes

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

Error Examples

400 Bad Request - Missing Parameter

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

401 Unauthorized - Invalid Token

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid token"
}

429 Too Many Requests - Rate Limit

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

Best Practices

Encode Special Characters

Always use URL encoding for spaces and special characters:

# Correct
curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Eiffel%20Tower%20Paris"
 
# Incorrect
curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Eiffel Tower Paris"

Use Precise Queries

The more precise the query, the better the results:

# Good: Complete address
curl "...?query=10%20Downing%20Street%2C%20Westminster%2C%20London%2C%20UK"
 
# Less good: Partial address
curl "...?query=10%20Downing%20Street"

Handle Empty Results

An empty array [] is returned if no results match:

# Check before accessing data
RESULT=$(curl -s "...?query=nonexistent_address" -H "Authorization: Bearer $TOKEN")
if [ "$(echo $RESULT | jq 'length')" -eq 0 ]; then
  echo "No results found"
fi

Limits

Limit	Value
Maximum results	50 per request
`query` length	500 characters
Encoding	UTF-8
Counting	1 request against quota

Technical Notes

Coordinates use the WGS84 system (same as GPS)
Results are sorted by relevance score in descending order
An empty array [] is returned if no results are found
Requests are counted against your quotas (even for 4xx errors)

Next Steps

Reverse Geocoding

Convert coordinates to an address.

Autocomplete

Real-time suggestions.

Batch Geocoding

Geocode multiple addresses at once.