# Geocoding search: free text in, GeoJSON out

> geolith search is a forward geocoding API: send GET https://api.geolith.app/v1/search?text=… with your API key and get a GeoJSON FeatureCollection of matching addresses, streets, places and points of interest, best first. In the India benchmark (200 queries per set, 20 Oct 2026) its first result was correct for 95.0% of OSM addresses, 95.0% of OSM places and 93.0% of Overture POIs. The data is OpenStreetMap plus Overture Maps, and the free plan includes 100,000 requests a month.

## What is forward geocoding?

Forward geocoding is turning a text description of a place, such as an address, a street, a town or a point of interest, into geographic coordinates (latitude and longitude). geolith does it with GET https://api.geolith.app/v1/search, which returns matching places as GeoJSON features ranked best first, each with a label, a stable gid and its address parts.

## One request, ranked results

Pass the text the user typed. geolith finds every place whose name and address words match, then ranks by how well the words fit and how important the place is. Each result carries a label you can show as-is, a stable gid, its layer and the address parts.

- text: the query, for example "Unter den Linden, Berlin", "東京タワー" or "MG Road, Bengaluru".
- size: 1 to 40 results, default 10.
- layers: venue, address, street, locality, county, region, country.
- boundary.country: ISO codes such as IN or FR,BE to keep results in those countries.
- focus.point.lat and focus.point.lon: rank places near a point higher.
- lang: return names in a language, for example hi or mr.
- categories: keep only POIs in categories such as food, health or education.

Request:

```bash
curl "https://api.geolith.app/v1/search?text=eiffel%20tower&size=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## What comes back

A GeoJSON FeatureCollection. Coordinates are [longitude, latitude], as GeoJSON requires. The geocoding block echoes the parsed query and links the attribution page.

Response (200):

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [2.294496, 48.858262] },
      "properties": {
        "gid": "geolith:venue:4611686018432401268",
        "layer": "venue",
        "name": "Tour Eiffel",
        "label": "Tour Eiffel, Paris 7e Arrondissement, Paris, Île-de-France, France",
        "category": ["attraction"],
        "street": "Avenue Anatole France",
        "neighbourhood": "Paris 7e Arrondissement",
        "locality": "Paris",
        "county": "Paris",
        "region": "Île-de-France",
        "postalcode": "75007",
        "country": "France",
        "country_code": "FR",
        "confidence": 1,
        "source": "geolith"
      },
      "bbox": [2.293312, 48.857475, 2.29569, 48.859045]
    }
  ],
  "geocoding": {
    "version": "0.2",
    "attribution": "https://console.geolith.app/attribution",
    "query": { "text": "eiffel tower", "size": 1, "ranking": "importance" }
  }
}
```

## Structured search for split address forms

When your form already splits the address, call /v1/search/structured with address, locality, region, postalcode and country. Every word of every field you set is required; when that finds too few places, geolith relaxes to about three quarters of the words. A two-letter country filters by country instead of matching words.

## From any language

It is a plain HTTPS GET with JSON back, so any HTTP client works. The key goes in an Authorization: Bearer header (servers) or ?api_key= (browsers, with a publishable key).

JavaScript (fetch):

```js
const url = new URL('https://api.geolith.app/v1/search');
url.searchParams.set('text', 'MG Road, Bengaluru');
url.searchParams.set('size', '5');

const res = await fetch(url, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
if (!res.ok) throw new Error(`geolith ${res.status}`);
const { features } = await res.json();

for (const f of features) {
  const [lon, lat] = f.geometry.coordinates; // GeoJSON order: lon, lat
  console.log(f.properties.label, lat, lon);
}
```

## Questions

### What does the geolith geocoding API cost?

The Free plan includes 100,000 requests a month with commercial use allowed if you show attribution. Starter is $19 a month for 1,000,000 requests, Growth $99 for 7,500,000 and Scale $299 for 25,000,000.

### Which order are the coordinates in?

GeoJSON order: [longitude, latitude]. geometry.coordinates[0] is the longitude and geometry.coordinates[1] is the latitude.

### How accurate is it?

In the India benchmark run on 20 Oct 2026 with 200 queries per set, geolith was right first time for 95.0% of OSM addresses, 95.0% of OSM places, 84.5% of OSM POIs and 93.0% of Overture POIs. The full table and method are on the benchmarks page of the API docs.

## Guides

- https://geolith.app/guides/reverse-geocoding-javascript
- https://geolith.app/guides/geocode-a-csv

## Sources

1. [geolith search benchmarks: engines](https://docs.geolith.app/search/benchmarks/engines), geolith (read 2026-10-22)
2. [RFC 7946: The GeoJSON Format](https://www.rfc-editor.org/rfc/rfc7946), IETF (read 2026-10-22)

Get a free API key (100,000 requests a month): https://console.geolith.app/signup