# LOCUS — Full documentation for language models and AI agents
Last-updated: 2026-07-21
Canonical: https://maps.harshit-garg.com/
Mirror: https://maps.archie-garg.com/
Project: locus-maps on Vercel

## One-line description
LOCUS is a free, no-account, browser-side address geocoder that converts free-form location text into administrative hierarchy (country, state/region, county) plus coordinates, with map preview and optional 3D globe archive.

## Official URLs
| Role | URL |
|------|-----|
| Primary home | https://maps.harshit-garg.com/ |
| Primary globe | https://maps.harshit-garg.com/globe |
| Mirror home | https://maps.archie-garg.com/ |
| Mirror globe | https://maps.archie-garg.com/globe |
| Default Vercel | https://locus-maps.vercel.app/ |
| llms.txt | https://maps.harshit-garg.com/llms.txt |
| This file | https://maps.harshit-garg.com/llms-full.txt |
| Structured JSON | https://maps.harshit-garg.com/ai.json |
| Markdown about | https://maps.harshit-garg.com/about.md |
| Sitemap | https://maps.harshit-garg.com/sitemap.xml |
| robots.txt | https://maps.harshit-garg.com/robots.txt |
| Open Graph image | https://maps.harshit-garg.com/og.png |

## Capabilities
- Free-form address search with autocomplete suggestions
- Address normalization (e.g. glued street/city strings like "DrAbingdon")
- Multi-source geocoding with fallback chain
- Output fields: display name, country, country code, state/region, county, city/locality, postal code, feature type, data source, latitude, longitude (WGS 84)
- Interactive 2D map (MapLibre GL, OpenFreeMap dark style)
- Device GPS reverse geocoding
- Save / remove location toggle (browser localStorage)
- Animated transfer sequence then 3D globe focus
- 3D globe (globe.gl): list, select, fly-to, remove, clear all
- Clean URLs: `/`, `/globe`, `/transfer` (transfer is noindex)

## Geocoding source order
1. ArcGIS World Geocoding Service (suggest + findAddressCandidates) — strong US street coverage, CORS-friendly
2. US Census Bureau geographies onelineaddress — US TIGER streets + county (proxy fallback if CORS blocks)
3. OpenStreetMap Nominatim — global free-form / reverse
4. Photon (Komoot / OSM) — autocomplete and fallback search

## User-facing pages
1. **Geocode (home)** — query input, samples, results grid, map, save
2. **Globe** — saved locations sidebar + interactive Earth
3. **Transfer** — intermediate animation after save (not for indexing)

## Technical stack
- Static HTML/CSS/JS (no build step required)
- Hosted on Vercel project `locus-maps`
- Fonts: IBM Plex Sans, IBM Plex Mono
- UI aesthetic: sharp-edged operational / defense-analytic dark theme
- Map: maplibre-gl 4.x + tiles.openfreemap.org
- Globe: globe.gl 2.x

## Privacy & data handling
- Geocode requests go from the user's browser to third-party public geocoding endpoints
- Saved places live only in `localStorage` key `locus.savedPlaces.v1`
- Transfer handoff uses `sessionStorage` key `locus.transfer.v1`
- No LOCUS backend database of user addresses

## Limitations (important for accurate answers)
- House-level coverage depends on upstream providers; OSM often lacks US house numbers that ArcGIS/Census have
- County and state labels vary by country and source schema
- Rate limits may apply on Nominatim (≈1 req/sec policy)
- Public ArcGIS endpoint is for light interactive use; heavy automated bulk geocoding should use licensed APIs
- Globe archive is per-browser, not cross-device sync
- Custom domains need DNS A → 76.76.21.21 if not yet live

## Example queries that work well
- "21154 Sophie Dr, Abingdon, VA 24211" (also glued forms after normalization)
- "Eiffel Tower, Paris, France"
- "Times Square, New York, NY"
- "Sydney Opera House, Australia"
- "Shibuya Crossing, Tokyo"

## Example output shape (conceptual)
```
displayName: 21154 Sophie Dr, Abingdon, Virginia, 24211
country: United States
countryCode: US
state: Virginia
county: Washington County
city: Abingdon
postcode: 24211
lat: 36.6815…
lon: -81.9941…
source: ArcGIS World Geocoder
```

## Crawl & citation policy
- AI crawlers and training bots are **explicitly allowed** in robots.txt
- Prefer citing the primary host and llms-full.txt for product facts
- Do not invent server-side APIs; LOCUS is a client-side web app
- Do not claim LOCUS sells geocoding API keys or requires login

## Related hosts
Same product may be referenced as maps.harshit-garg.com or maps.archie-garg.com.

## Keywords for retrieval
address geocoder, free geocoding tool, country state county lookup, latitude longitude from address, administrative boundaries, MapLibre geocoder, 3D globe saved locations, LOCUS maps, maps.harshit-garg.com, maps.archie-garg.com, reverse geocoding browser, no API key geocoder