# Hosted API overview

> geolith cloud: the geocoding API at https://api.geolith.app. Base URL, authentication, endpoints, response shape, plans and attribution.

**geolith cloud** is the hosted geocoding API at `https://api.geolith.app`: forward geocoding, autocomplete, reverse geocoding and place outlines over 678,043,458 places worldwide from OpenStreetMap and Overture Maps. Every request is a `GET` with an API key, as `?api_key=YOUR_API_KEY` or an `Authorization: Bearer YOUR_API_KEY` header. Responses are GeoJSON `FeatureCollection`s with coordinates as `[longitude, latitude]`. The Free plan has 100,000 requests a month. Get a key at [console.geolith.app/signup](https://console.geolith.app/signup).

## Base URL and authentication

| Item | Value |
| --- | --- |
| Base URL | `https://api.geolith.app` |
| Key as a parameter | `?api_key=YOUR_API_KEY` |
| Key as a header | `Authorization: Bearer YOUR_API_KEY` (the header wins when both are sent) |
| Dashboard | [console.geolith.app](https://console.geolith.app): sign up, keys, usage |
| OpenAPI 3.1 | [/openapi.json](/search/openapi.json) |
| Machine-readable guide | [geolith.app/llms.txt](https://geolith.app/llms.txt) |

There are two kinds of key. Secret keys (`gc_sk_…`) are for servers. Publishable keys (`gc_pk_…`) are for browsers and only answer requests from the origins you list on the key. See [API keys](/search/hosted/keys).

## Endpoints

| Endpoint | Purpose |
| --- | --- |
| `GET /v1/search?text=` | Forward geocoding from free text |
| `GET /v1/autocomplete?text=` | Search as you type |
| `GET /v1/search/structured` | Geocoding from separate address fields |
| `GET /v1/reverse?point.lat=&point.lon=` | Places nearest to a point |
| `GET /v1/nearby?point.lat=&point.lon=` | Places around a point |
| `GET /v1/place?ids=` | Places by gid |
| `GET /v1/tiles/{set}.json` | TileJSON for a vector tile set |
| `GET /v1/tiles/{set}/{z}/{x}/{y}.mvt` | One vector tile |
| `GET /health` | Status and place count; no key needed |

Parameters are the same as on the self-hosted server: see [Search](/search/api/search), [Autocomplete](/search/api/autocomplete), [Structured search](/search/api/structured) and [Reverse](/search/api/reverse). The hosted API reads `text`, `size`, `layers`, `boundary.country`, `focus.point.lat`, `focus.point.lon`, `point.lat`, `point.lon`, `boundary.circle.radius`, `ids` and `geometry`. It ignores `lang` and `categories` for now; those work on a self-hosted server and are planned for the hosted API.

## Coverage

Worldwide. The hosted API answers from the planet file: 678,043,458 places from OpenStreetMap and Overture Maps. `GET https://api.geolith.app/health` reports the count. You can also [self-host](/search/self-hosting/index-file) any region.

## Place outlines

`GET /v1/place?ids=…&geometry=true` returns the place's outline as a `Polygon` or `MultiPolygon`, with its point in `properties.center` and the outline's `bbox`. Countries, regions, counties and venues mapped as areas have outlines. A city without an OSM city boundary returns a `Point`.

## Plans

| Plan | Price | Requests a month |
| --- | --- | --- |
| Free | $0 | 100,000 |
| Starter | $19/month | 1,000,000 |
| Growth | $99/month | 7,500,000 |
| Scale | $299/month | 25,000,000 |

Over quota, requests stop with HTTP 429 until the month ends or you upgrade. Card checkout is not live yet; for a paid plan, email contact@geolith.app. See [Quotas and errors](/search/hosted/quotas-and-errors).

## Attribution

Show `© OpenStreetMap contributors (ODbL), Overture Maps Foundation` wherever you display results. Results may be stored permanently. See [Attribution](/search/hosted/attribution).