API / Reverse Search

GET /search/reverse

Reverse Search API.

Reverse geocoding - convert a coordinate into the nearest human-readable address, sorted by distance from the queried point.

Pass a latitude and longitude, get back the closest streets, addresses, and places within 2 km - ordered by geodesic distance. Returns the same structured fields as the Search API: street, suburb, city, postcode, province, and country.

Part of the Search API family alongside Search and Search Detail.

Get API Key View Docs

API OPERATIONAL · View status

# Reverse geocode - nearest address to a coordinate
curl "https://api.farun.one/search/reverse" \
  -H "X-RapidAPI-Key: YOUR_KEY" \
  -H "X-RapidAPI-Host: farun-maps.p.rapidapi.com" \
  -G \
  --data-urlencode "lat=-33.9249" \
  --data-urlencode "lon=18.4241" \
  --data-urlencode "size=3"

# Filter to addresses only
curl "https://api.farun.one/search/reverse" \
  -H "X-RapidAPI-Key: YOUR_KEY" \
  -G \
  --data-urlencode "lat=-33.9249" \
  --data-urlencode "lon=18.4241" \
  --data-urlencode "types=address"

const params = new URLSearchParams(
  lat:  "-33.9249",
  lon:  "18.4241",
  size: "3",
);

const res = await fetch(
  `/api/reverse-proxy?$${params}` // proxy - key server-side
);
const data = await res.json();

// Nearest result
const nearest = data.results[0];
console.log(nearest.display_name);
// "Bree Street, Cape Town City Bowl, 8001"
console.log(nearest.distance_m);
// 34.2

import requests

r = requests.get(
    "https://api.farun.one/search/reverse",
    headers={
        "X-RapidAPI-Key":  "YOUR_KEY",
        "X-RapidAPI-Host": "farun-maps.p.rapidapi.com",
    },
    params={
        "lat":  -33.9249,
        "lon":  18.4241,
        "size": 3,
    },
)
data = r.json()
nearest = data["results"][0]
print(nearest["display_name"], nearest["distance_m"])
# "Bree Street, Cape Town City Bowl, 8001"  34.2

Search radius

2 km from point

Sort order

Distance - nearest first

Max results

10 per request

How reverse geocoding works

Coordinate in. Address out. Sorted by distance.

The reverse geocoding query filters all indexed documents to within 2 km of the queried coordinate using a geo_distance filter, then sorts them by geodesic distance in ascending order. The nearest result is always first.

Step 1

Geo-Distance Filter

A geo_distance filter restricts the search to documents whose location field falls within 2 km of the queried lat/lon. This keeps results relevant and the query fast - no full index scan.

Filter radius: 2 km. No results returned beyond this range.

Step 2

Arc Distance Sort

Results are sorted by _geo_distance using arc distance type, the most accurate geodesic calculation for real-world distances. The sort value is returned as distance_m in each result.

Sort: _geo_distance asc. Unit: metres. Type: arc.

Step 3

Structured Address Response

Each result returns the same structured fields as a forward search - street, suburb, city, postcode, province, country plus a distance_m field showing how far the result is from your queried coordinate.

Geometry excluded. Use Search Detail for GeoJSON shape.

Who uses it

Coordinates are useless without an address.

Every system that records a GPS coordinate eventually needs to show it as an address. The Reverse Search API is the step between raw lat/lon from a device, a click, a telematics ping and the human-readable location that appears in reports, notifications, and dispatch UIs.

Telematics & Fleet

GPS Ping to Delivery Address

When a vehicle stops at a coordinate, reverse geocode it to show the driver and dispatcher a readable address in the trip history, exception report, or live tracking panel without requiring them to interpret raw coordinates.

Map & Location UX

Map Click to Address Display

When a user taps or clicks a point on the map to select a location, reverse geocode the clicked coordinate and display the nearest street address as a confirmation label so they know exactly what they've pinned.

Insurance & Claims

Incident Location from GNSS

Convert a recorded GPS coordinate from a vehicle or field device into a human-readable address for claims documents, adjuster reports, and compliance filings without manual address lookup or external map tools.

Field Operations

Current Location Label for Crews

Show field crew members their current location as a readable street address when they check in or submit a job update using the device GPS coordinate to query the nearest address without them having to type anything.

Response shape

Structured address fields plus distance in metres.

Every result in the array includes full structured address components and a distance_m field - the geodesic distance in metres from the queried coordinate to that result. Results are always sorted nearest-first.

lat / lon Echoed input coordinate
took_ms Elasticsearch internal query time in milliseconds
results[].id Document ID - pass to Search Detail for GeoJSON geometry
results[].distance_m Distance in metres from queried coordinate to this result
results[].display_name Full human-readable address label
results[].doc_type address · street · place · poi
results[].street Street name
results[].suburb Suburb or neighbourhood
results[].city City
results[].postcode Postal code
results[].province Province or state
results[].location {"lat": float, "lon": float} - coordinate of the matched record

GET /search/reverse?lat=-33.9249&lon=18.4241 200 OK

{
  "lat":     -33.9249,
  "lon":     18.4241,
  "took_ms": 6,
  "results": [
    {
      "id":           "way/123456789",
      "distance_m":   34.2,
      "doc_type":     "street",
      "display_name": "Bree Street, Cape Town City Bowl, 8001",
      "street":       "Bree Street",
      "suburb":       "Cape Town City Bowl",
      "city":         "Cape Town",
      "postcode":     "8001",
      "province":     "Western Cape",
      "country":      "ZA",
      "location": { "lat": -33.9252, "lon": 18.4238 }
    },
    {
      "id":           "node/987654321",
      "distance_m":   71.8,
      "doc_type":     "poi",
      "display_name": "Mojo Market, Bree Street",
      "category":     "marketplace",
      "location": { "lat": -33.9255, "lon": 18.4249 }
    }
  ]
}

Geometry excluded from results. Use Search Detail with the result id to fetch the full GeoJSON shape.

Endpoint reference

GET https://api.farun.one/search/reverse

Query parameters

lat req

float

Latitude of the coordinate to reverse geocode.

lon req

float

Longitude of the coordinate to reverse geocode.

size

integer

Max results to return. Default: 5. Max: 10.

types

string

Comma-separated filter: address · street · place · poi. Omit to return all types.

Response codes

200 application/json Results array. Empty array if nothing found within 2 km.

400 Bad request lat or lon missing or not a valid float.

401 Unauthorized Missing or invalid RapidAPI key.

429 Rate limited Daily pool exhausted. Upgrade on RapidAPI.

503 Unavailable Search backend unavailable.

Search radius

2 km hard limit

Sort

Nearest first - arc distance

Max results

10 per request

Geometry

Excluded - use Search Detail

Types filter

address, street, place, poi

Distance field

distance_m - metres from point

Integration example

Map click → reverse geocode - JavaScript JavaScript

// Reverse geocode on map click - show nearest address
map.on("click", async (e) => {
  const { lat, lng } = e.lngLat;

  const params = new URLSearchParams(
    lat:   String(lat),
    lon:   String(lng),
    size:  "1",     // nearest only
    types: "address,street",
  );

  const res  = await fetch(`/api/reverse-proxy?$${params}`);
  const data = await res.json();

  if (data.results.length) {
    const nearest = data.results[0];
    showPopup(e.lngLat, {
      title:    nearest.display_name,
      subtitle: `$${nearest.distance_m}m away`,
      id:       nearest.id, // for Search Detail
    });
  }
});

Always proxy server-side. Never call the API directly from client-side JavaScript, your RapidAPI key would be exposed. Route requests through your own backend endpoint.