ATGeo Demos

A monorepo of sample web & mobile apps and libraries that demonstrate uses of the ATGeo lexicon — a geographic place lexicon and Gazetteer lookup service for AT Protocol applications (such as Bluesky).

The primary aim of these sample apps is to demonstrate the concepts behind ATGeo and to show how the underlying lexicon, records, and XRPC APIs can be used in practice. They are intentionally illustrative rather than fully featured products.

---

Live demos

Published on GitHub Pages: https://yozlet.github.io/atgeo-demos/

Deploys automatically from main via GitHub Actions (.github/workflows/pages.yml).

What is ATGeo?

ATGeo is a community effort, stewarded under the Lexicon Community and the ATProtocol-Community organization, to bring structured location / place data to the ATmosphere. It consists of:

• A place lexicon describing how points of interest are represented as AT Protocol records.
• A Gazetteer — an AT Protocol AppView that serves location information and exposes a public XRPC API for searching and retrieving place records.

Key lexicons & namespaces

NSID	Purpose
org.atgeo.place	Core place record definition
org.atgeo.places.foursquare	Place records sourced from Foursquare
org.atgeo.places.overture	Place records sourced from Overture Maps
org.atgeo.places.wof	Place records sourced from Who's on First
community.lexicon.location.geo	Latitude / longitude coordinates
community.lexicon.location.hthree	H3 hexagonal grid cells
community.lexicon.location.address	Postal addresses
community.lexicon.location.bbox	Bounding boxes

Gazetteer XRPC endpoints

The Gazetteer is reachable at https://places.atgeo.org/xrpc/ and exposes:

• org.atgeo.searchRecords — search for places by text query and/or geographic location (lat/lon, bounding box). At least one of q, latitude/longitude, or bbox is required.
• com.atproto.repo.getRecord — fetch a single place record by collection and rkey from the gazetteer repo (places.atgeo.org). No authentication required.

---

Repository layout

atgeo-demos/
├── docs/                       # Pointers to ATGeo, AT Protocol & related docs
├── samples/
│   └── tiles/                  # Local tile exports (served by place-browser via Vite publicDir)
├── packages/
│   └── atgeo-client/           # TypeScript helpers: quadkeys, resolveCoverage, place parsing (XRPC pending)
└── apps/
    ├── place-browser/          # Map + pin → leaf tiles + Place List (local tile fetch)
    ├── favourite-places/       # Keep a list of favourite places (sample app)
    └── social-presence/        # Foursquare-like social presence app (sample app)

docs/

Up-to-date documentation, links, and pointers covering the ATGeo lexicon, Gazetteer APIs, the wider Lexicon Community effort, and the underlying AT Protocol primitives (Lexicons, NSIDs, XRPC).

packages/atgeo-client

TypeScript helpers for ATGeo place coverage. v1 ships quadkey primitives (Bing/Web Mercator, digits 0–3), snapPointToQueryBbox (0.02° privacy grid), resolveCoverage over a static covering index, and place helpers (parseTilePlaces, fuzzyMatch, filterPlaces, distanceMeters, rankPlacesByDistance). The v1 runtime covering index is exported from packages/atgeo-client/src/fixtures/sf-023010-covering.json. XRPC wrappers for org.atgeo.searchRecords and com.atproto.repo.getRecord are planned for a future release.

samples/tiles

Sample OSM place tile exports under samples/tiles/ (e.g. 20260731T200638/{qk6}/{qk}.json). Place-browser serves this tree via Vite publicDir and fetches leaf bodies after resolveCoverage; no live Gazetteer XRPC in v1.

apps/place-browser

Mobile-first web demo: place a pin on a San Francisco map, resolve covering leaf tile IDs, fetch tile JSON locally, and browse a Place List (fuzzy search + distance ranking) or Tile List (copyable leaf IDs). Polygon overlays show tile coverage. Precise coordinates stay in the browser.

npm install
npm run dev:place-browser

apps/favourite-places

A sample app demonstrating the simplest ATGeo use case: searching the Gazetteer and keeping a personal list of favourite places as AT Protocol records.

apps/social-presence

A sample Foursquare-like social presence app demonstrating check-ins and place-based social activity built on top of the ATGeo place lexicon.

---

Further reading

• ATGeo website — homepage, with the lexicon reference, API docs, and usage guides:
  • Place lexicon
  • XRPC API
  • Usage guide
  • Known gaps & roadmap
  • FAQ
  • OpenStreetMap integration
  • Overture Maps integration
  • Foursquare integration
• ATGeo website source (ATProtocol-Community/atgeo.org)
• atgeo-marker experiment (ATProtocol-Community/atgeo-marker)
• Lexicon Community — governance and reference lexicons (community.lexicon.*).
• AT Protocol Community Wiki — ATGeo working group
• ATmosphereConf 2025 — ATGeo: Location Data Working Group

AT Protocol foundations

• AT Protocol overview
• Lexicon specification
• XRPC (HTTP API) specification
• Publishing lexicons
• Glossary
• @atproto/xrpc on npm — official TypeScript XRPC client used as the transport layer for packages/atgeo-client.

---

Status

• packages/atgeo-client — v1: quadkey utilities, resolveCoverage, place parsing/filter/rank helpers, unit tests with golden pins. XRPC client pending.
• apps/place-browser — v1: map shell, pin placement, local tile fetch, Place List + Tile List tabs, polygon overlays.
• apps/favourite-places, apps/social-presence — scaffold only.

License

TBD — see individual sub-projects.