GET /v1/geocoding/reverse

Converts geographic coordinates (latitude/longitude) into a structured, readable address. Ideal for displaying a user's current position or enriching GPS data.

Endpoint

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

Authentication

This endpoint requires authentication via a JWT Bearer token.

Authorization: Bearer YOUR_JWT_TOKEN

Parameters

Query Parameters

Parameter	Type	Required	Description	Range
`lat`	`number`	Yes	Latitude in decimal degrees	-90 to 90
`lon`	`number`	Yes	Longitude in decimal degrees	-180 to 180

Coordinates must be in WGS84 format (GPS standard). Precision up to 7 decimal places is accepted.

Requests

Basic Request

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

Precise Coordinates

curl "https://places.gotravelyzer.com/v1/geocoding/reverse?lat=48.8582599&lon=2.2945006" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example: Big Ben, London

curl "https://places.gotravelyzer.com/v1/geocoding/reverse?lat=51.5007&lon=-0.1246" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example: Statue of Liberty, New York

curl "https://places.gotravelyzer.com/v1/geocoding/reverse?lat=40.6892&lon=-74.0445" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

Success Example (200 OK)

{
  "place_id": 2681977,
  "display_name": "Eiffel Tower, 5, Avenue Anatole France, Quartier des Invalides, 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": {
    "tourism": "Eiffel Tower",
    "house_number": "5",
    "road": "Avenue Anatole France",
    "quarter": "Quartier des Invalides",
    "suburb": "Paris 7e Arrondissement",
    "city": "Paris",
    "state": "Île-de-France",
    "postcode": "75007",
    "country": "France",
    "country_code": "fr"
  },
  "confidence": 0.95
}

Unlike Forward Geocoding which returns an array, Reverse Geocoding returns a single object corresponding to the place nearest to the coordinates.

Response Fields

Field	Type	Description
`place_id`	`number`	Unique identifier of the place
`display_name`	`string`	Complete formatted address
`lat`	`number`	Latitude of the place center
`lon`	`number`	Longitude of the place center
`country`	`string`	Country name
`city`	`string`	City name (if applicable)
`category`	`string`	Main category
`type`	`string`	Specific type
`importance`	`number`	Importance score (0-1)
`boundingbox`	`number[]`	Bounding area [south, north, west, east]
`address`	`object`	Structured address components
`confidence`	`number`	Result confidence score (0-1)

Address Fields

Field	Description	Example
`house_number`	Street number	`"5"`
`road`	Street name	`"Avenue Anatole France"`
`quarter`	Quarter	`"Quartier des Invalides"`
`suburb`	District	`"Paris 7e Arrondissement"`
`city`	City	`"Paris"`
`state`	Region/State	`"Île-de-France"`
`postcode`	Postal code	`"75007"`
`country`	Country	`"France"`
`country_code`	ISO code	`"fr"`

HTTP Codes

Code	Status	Description
`200`	OK	Place found
`400`	Bad Request	Missing or invalid coordinates
`401`	Unauthorized	Missing or invalid JWT token
`404`	Not Found	No place found at coordinates
`429`	Too Many Requests	Request limit exceeded
`502`	Bad Gateway	Service error
`503`	Service Unavailable	Service temporarily unavailable

Error Examples

400 Bad Request - Missing Parameters

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "lat and lon parameters are required"
}

400 Bad Request - Out of Range Coordinates

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "lat must be between -90 and 90"
}

404 Not Found - No Place

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No location found at these coordinates"
}

Use Cases

User GPS Position

Convert a user's GPS position into a readable address:

# Get the address of the current position
LAT=48.8584
LON=2.2945
 
curl "https://places.gotravelyzer.com/v1/geocoding/reverse?lat=$LAT&lon=$LON" \
  -H "Authorization: Bearer $TOKEN"

Map Click

Display the address when a user clicks on a map:

# Click coordinates
curl "https://places.gotravelyzer.com/v1/geocoding/reverse?lat=51.5074&lon=-0.1278" \
  -H "Authorization: Bearer $TOKEN"

Data Enrichment

Enrich GPS data with readable addresses:

#!/bin/bash
# Script to enrich a list of coordinates
 
while IFS=',' read -r lat lon; do
  RESULT=$(curl -s "https://places.gotravelyzer.com/v1/geocoding/reverse?lat=$lat&lon=$lon" \
    -H "Authorization: Bearer $TOKEN")
 
  ADDRESS=$(echo $RESULT | jq -r '.display_name // "Not found"')
  echo "$lat,$lon,$ADDRESS"
done < coordinates.csv

Best Practices

Coordinate Precision

Use at least 4 decimal places for acceptable precision:

Decimals	Approximate Precision
1	~10 km
2	~1 km
3	~100 m
4	~10 m
5	~1 m
6-7	Centimeter

# Recommended: 4-6 decimal places
curl "...?lat=48.8584&lon=2.2945"
 
# Too imprecise
curl "...?lat=48.9&lon=2.3"

Handling Areas Without Data

Some areas (oceans, deserts, sparsely populated zones) may not have data:

# Ocean area - may return 404
curl "https://places.gotravelyzer.com/v1/geocoding/reverse?lat=45.0&lon=-30.0" \
  -H "Authorization: Bearer $TOKEN"

Limits

Limit	Value
Latitude	-90 to 90
Longitude	-180 to 180
Accepted precision	Up to 7 decimal places
Counting	1 request against quota

Technical Notes

Coordinates use the WGS84 system (global GPS standard)
The confidence field indicates result reliability (0 to 1)
A confidence score > 0.8 is considered reliable
Sparsely populated or oceanic areas may return a 404

Next Steps

Forward Geocoding

Convert an address to coordinates.

Autocomplete

Real-time search suggestions.

Batch Geocoding

Geocode multiple requests at once.