Client SDKs

The ATGeo client SDKs search places on the device, so the server never learns what you searched for or where you are, exactly. The few methods that do tell the server a keyword have Keyword in their names.

The home page map runs on the JavaScript SDK. There are five SDKs: JavaScript/TypeScript (the reference), Swift, Kotlin, Python and Rust. All of them are pre-release.

Why an SDK

A server that can search can log what you typed. So the gazetteer's main way of finding places is tiles: static files of places. A client asks which tiles cover an area, downloads them, and does the matching, filtering and ranking itself.

That's a fair bit of work: snapping regions to a grid, fetching tiles eight at a time, de-duplicating, fuzzy matching, ranking, caching, crediting the data. The SDKs do it for you.

Tiles need a region, though. You can't find "Kyoto" in tiles without knowing roughly where Kyoto is. For that, the XRPC API also has a keyword search, org.atgeo.searchPlaces, which does tell the server what you typed. The SDKs keep the two apart by name: a method whose name contains Keyword may send your search text to the server, and no other method does. The option that carries text is text where it never leaves the device and keyword where it may.

The calls:

What you call What happens on the wire
searchNearby org.atgeo.getTiles, then one GET per tile
searchByKeyword one org.atgeo.searchPlaces, with the keyword
searchNearbyThenByKeyword what searchNearby sends, then, only if there's no solid nearby hit, what searchByKeyword sends
autocompleteByKeyword one org.atgeo.searchPlaces per call whose input could be accepted, prefixes included
getPlace nothing if the tile is cached, else org.atgeo.getPlace
describeService org.atgeo.describeService (cached for an hour)
describeTileset org.atgeo.describeTileset (not cached)

The client does no quadkey math. Tile URLs are opaque; the server works out which tiles cover a box.

The five SDKs

Language Repository Runs on Nearby Keyword getPlace
JavaScript / TypeScript atgeo-sdk-js Evergreen browsers, Node 20+, workers searchNearby searchByKeyword, searchNearbyThenByKeyword, autocompleteByKeyword getPlace
Swift atgeo-sdk-swift iOS 15, macOS 12, tvOS 15, watchOS 8, visionOS 1, Linux; Swift 6 searchNearby searchByKeyword, searchNearbyThenByKeyword, autocompleteByKeyword getPlace(origin:)
Kotlin atgeo-sdk-kotlin JVM 11+, Android API 24+ searchNearby searchByKeyword, searchNearbyThenByKeyword, autocompleteByKeyword getPlace
Python atgeo-sdk-python Python 3.11+ search_nearby search_by_keyword, search_nearby_then_by_keyword, autocomplete_by_keyword (async client) get_place
Rust atgeo-sdk-rs Rust 1.85+ (edition 2024) search_nearby search_by_keyword, search_nearby_then_by_keyword, autocomplete_by_keyword (async client) get_place

Every SDK also has describeService and describeTileset (describe_service and describe_tileset in Python and Rust).

The TypeScript client is the reference. The other four are ports: they share its fixtures and its port contract, and are meant to return the same places in the same order for the same server answers. Each port has a CONFORMANCE.md listing the margins where it differs, nearly all of them about malformed data that a compliant server never sends.

Status

Pre-release. None of the SDKs is on a package registry (npm, PyPI, crates.io, Maven Central); each stays unpublished until beta testing ends. Install from GitHub, pinned to a full commit SHA, not a branch. The API is still changing, and breaking changes land on main. Each language page has the install snippet; replace <commit-sha> with a commit you've tested.

Every search names a dataset, and can narrow it to a collection. There is no default dataset: leaving it out is an argument error, before any request.

dataset collection What is searched
given absent the whole dataset, every collection together
given given that collection

dataset: "openstreetmap.org" alone returns nodes, ways and relations in one list, which is usually what you want from OSM, since the element type is an accident of how the mapper drew it. dataset: "overturemaps.org" alone returns places and divisions together. A collection-filtered search keeps only records whose origin starts with urn:atgeo:{dataset}:{collection}:.

There is no merged ranking across datasets. importance is comparable across one dataset's tilesets (Overture places rank against Overture divisions) but not across datasets: an Overture place scoring 62 and an OSM place scoring 62 aren't equally important. If you want both, make two calls and decide how to interleave them. See Overture Places, Overture Divisions and OpenStreetMap for what each dataset holds.

Regions

searchNearby requires a region, and it's one of:

A box with minLon > maxLon crosses the antimeridian. The client sends two getTiles calls, one for each side, and merges the tiles. Invalid regions (non-finite or out-of-range coordinates, minLat > maxLat, a negative radius) are rejected before any request.

Results are filtered back to your region, not the snapped one: a point place is kept if it's inside, a place with only a bounding box is kept if the box touches the region, and a circle means the circle, not its enclosing square. A tight region in a sparse area can come back empty even though the client holds good places a couple of kilometers off. That's a feature of predictability, but watch for it in testing.

searchByKeyword's region is optional and is a bounding box only, never a circle: a circle invites the device's own position as its centre. It goes out snapped outward to whole degrees, so [-122.42, 37.77, -122.41, 37.78] is sent as -123,37,-122,38. Without a region, the whole dataset is searched.

Matching and sorting

With text, searchNearby sorts hits into two tiers before anything else. A place is tier 1 when every word of the text begins a word of one of its names (its own or a variant), ignoring case, accents and apostrophes, with other punctuation splitting words: mcdonalds finds McDonald's, st louis finds St. Louis, and qu finds Bar & Grill at the Old Quarry. Everything else is tier 2, a fuzzy match, scored with Jaro-Winkler. A tier-1 hit is always kept; a tier-2 hit is kept only if it scores at least 0.8, which keeps typos (starbux finds Starbucks) and drops near-random matches. Tier 1 comes first in every sort mode.

Mode Order, within each tier
fused (default) text similarity, best first; near-ties broken by importance, then distance. With no text: importance, then distance.
distance nearest first; then the smaller place (so the most specific place containing the centre leads), then importance, then similarity.
similarity text similarity, then distance. Requires text.

Ties on everything fall back to origin, so the order is deterministic.

The server's keyword search matches the same word-prefix way, but not fuzzily (starbux finds nothing there), and ranks by importance alone, at most 20 places. The SDK keeps the server's order.

What a hit has

Field Meaning
via tiles for a hit from searchNearby, keyword for one from the server's keyword search.
origin The place's identity, a URN like urn:atgeo:{dataset}:{collection}:{id}. May be absent on records from other producers. Pass it to getPlace.
collection The { dataset, collection } the place's data comes from, matched against the attribution, or none.
name The place's name, when it's a string.
location Where the place is: a point (lat, lon) and a box (south, west, north, east), each or both possibly absent.
place The place record, exactly as served. See the Lexicon.
importance An integer rank relative to its dataset, or none.
distance Nearby hits only. Metres from the region's centre to the nearest point of the place; 0 if the place contains the centre.
score Nearby hits only. Text similarity, 0 to 1; none if you gave no text.

A keyword hit has no distance or score: the server ranks by neither, and you can work out a distance from location yourself.

Attribution

Every search result carries an attribution list: the credit owed for the data the search used, one entry per (dataset, collection), sorted, with its licences and the URL of the upstream's attribution or copyright page. If you show a place, show the credit its data requires. It covers every tile the search used, not just the places that survived filtering, and includes the divisions a place's within names. getPlace returns the place's own attribution list too.

Disclosure

Every search result carries disclosed = { keyword, region }, a report of what the server learned during that one call. keyword is true if the keyword was sent. region is the grid, in degrees, of the finest region sent: 0.01 for a tile search, 1 for a keyword search with a box, none if no region went out (a nearby search answered entirely from cache, say). For searchNearby, keyword is always false. For searchNearbyThenByKeyword, it tells you which way the call went.

Overview versus complete

A nearby search result has two flags that mean different things:

They're independent. overview: true, complete: true is a perfectly good answer. If you want the full set, search a smaller region. For a deeper look, see the overview band in the XRPC docs.

Tile failures

A failed tile doesn't fail the search. It's skipped, counted, and listed in tileFailures (tile_failures in the snake-case SDKs), each with its URL, a kind and an error:

kind What happened
refused The tile URL wasn't an absolute http(s) URL, or carried credentials. No request was made.
status The tile answered with a non-2xx status (also recorded).
decode A 2xx whose body isn't a tile.
transport The fetch itself failed: network error, timeout, a body over the size cap.

There are no retries. A failed getTiles request is different: with no tile list there's nothing to degrade, so the search fails.

What goes on the wire

searchNearby:

Not on the wire: your search text, in any form, and your precise region or location. Those are used only on the device, for filtering, ranking and distance. Snapping hides where in a ~1 km cell you are; it doesn't hide the cell.

searchByKeyword sends the keyword exactly as you passed it, in one searchPlaces request with the dataset, the collection if any, and the box only if you gave one, snapped outward to whole degrees.

searchNearbyThenByKeyword sends what searchNearby sends. It then sends the keyword only if no nearby hit is tier 1 and the keyword could pass the server's two-character rule, and then it sends what searchByKeyword sends: with the nearby region's whole-degree box if you asked for keywordRegion: "degree", with no region for "none". You must pick one; there's no default.

autocompleteByKeyword sends what searchByKeyword sends, for every string that could be accepted, prefixes included. The server keeps no log of what it's sent, but a hostile operator could record what it receives. Debouncing reduces how many prefixes go out, and it's your app's choice; the SDKs don't do it for you.

Other calls. describeService and describeTileset send a request only if you call them. getPlace on a cache miss sends the origin you asked for. That's a sharper signal than a tile fetch: it tells the server which place you're looking at. It's meant for resolving a shared link, and the cache is checked first so that tapping a nearby result doesn't hit the network.

The server also sees your IP address and whatever headers your HTTP stack adds (the Swift, Kotlin, Python and Rust default transports keep these generic; in a browser, the JavaScript client's requests carry the browser's own), and it can tell which tiles you've fetched. The SDKs send no telemetry.

Caching

Tile URLs are immutable, so tiles cache in memory until evicted, least recently used first, up to 50 MiB by default. getTiles answers and the service description are held for an hour. Nothing is persisted; a new client starts cold. Search a region twice, or change only the text or sort, and the second search makes no requests. Keyword calls aren't cached: each is one request.

If you want a disk cache, supply a transport that has one. There's no prefetch method either: a no-text search of a big region is already a warm-up.

Errors

The server's error codes come through as the code on the SDK's error type, alongside the HTTP status, so you can tell a refused request (4xx) from a failed one (5xx). The list is open. The ones you'll see:

Code From Meaning
BboxTooLarge getTiles Over the tile budget and no overview band to fall back on. Ask for less.
DatasetNotFound getTiles, searchPlaces No tileset carries that dataset.
CollectionNotFound getTiles, searchPlaces The dataset exists, but not that collection.
KeywordRequired searchPlaces No word of the keyword is two or more characters long. searchByKeyword passes it through; the fallback and autocomplete skip such keywords, or treat the refusal as no answer.
PlaceNotFound getPlace No place with that origin.
TilesetNotFound describeTileset No tileset with that slug.
InvalidRequest any A malformed parameter, or a keyword over 256 bytes.
HttpError any A non-2xx without a parseable error body (usually a proxy or CDN).

A 2xx body with nothing usable in it raises a separate decoding error. Bad arguments (no dataset, an invalid region, a circle given to searchByKeyword, similarity sort without text) fail before any request, with the language's usual argument error. An autocompleter's call that a newer call replaced ends with a cancellation (or, in Rust, Superseded) that you ignore. Each language page has the details.

What's deliberately absent

Where to go next

Each SDK's README is its full reference; the language pages here are quickstarts. The design rationale lives in the garganorn repo's client SDK doc, and the exact behaviour in the port contract. Using the public server? Be kind to it, or run your own.