# Who Arrives

> Who Arrives is a free, open-source IP geolocation API for the current caller's public IP address, country or region, approximate location, timezone, and network (ASN). It runs on Cloudflare Workers and requires no signup or API key.

The documentation website is https://who-arrives.fthux.com/. The API base URL is https://who-arrives-api.fthux.com/. These are separate hosts: send API requests to the API host.

## Documentation

- [Website and quick start](https://who-arrives.fthux.com/): Product overview, interactive examples, and frequently asked questions.
- [API usage and query fields](https://who-arrives.fthux.com/#usage): curl and JavaScript examples and the eight optional enrichment selections.
- [Behavior and limitations](https://who-arrives.fthux.com/#details): Caller-only lookup, missing values, approximate coordinates, caching, and HTTP errors.
- [OpenAPI specification](https://who-arrives.fthux.com/openapi.json): OpenAPI 3.1 machine-readable request parameters, response schemas, and supported methods.
- [ARD manifest](https://who-arrives.fthux.com/.well-known/ard.json): Agentic Resource Discovery entry describing this API and linking to its OpenAPI specification.
- [Source repository](https://github.com/fthux/who-arrives): Cloudflare Worker source and self-hosting instructions.

## API usage

- Basic lookup: `GET https://who-arrives-api.fthux.com/`
- Selected enrichment: `GET https://who-arrives-api.fthux.com/?fields=names,flag,time`
- All enrichment: `GET https://who-arrives-api.fthux.com/?fields=all`
- Supported methods: `GET`, `HEAD`, and `OPTIONS`. Browser CORS is supported with `Access-Control-Allow-Origin: *`.
- Basic response keys: `ip`, `countryOrRegion`, `continent`, `city`, `region`, `postalCode`, `location`, `metroCode`, and `asn`.
- `fields` accepts comma-separated, case-sensitive selections: `names`, `flag`, `ipVersion`, `time`, `capitals`, `currencies`, `languages`, and `callingCodes`. `all` requests every selection.
- Missing or empty `fields` returns basic data only. Repeated `fields` parameters are merged; whitespace, duplicates, and empty tokens are ignored.
- Requested additions appear under `enrichment`; basic fields remain unchanged. Unavailable values are `null`; known empty lists are `[]`.
- Unknown fields or unsupported query parameters return HTTP 400. Unknown paths return 404. Unsupported methods return 405.

## Interpretation and limits

- Only the current caller's connection is queried. Arbitrary IP addresses and batch lookups are not supported; there is no `ip` query parameter.
- A browser request describes that browser's public connection. A request from a server, proxy, crawler, or AI tool describes its own outgoing connection, not the end user's connection.
- IPv4 and IPv6 are supported. Geolocation coordinates are approximate and are not device GPS coordinates.
- Country or region languages, currencies, capitals, flags, and calling codes are reference data, not evidence of an individual's identity or preferences.
- IP, geolocation, and ASN data come from Cloudflare request metadata. Enrichment uses bundled country reference data or local computation, without an external geolocation lookup.
- API responses use `Cache-Control: private, no-store, max-age=0` and should not be treated as static facts about a person.
- The documentation does not publish an uptime guarantee. Cloudflare platform and account limits apply; lack of an API key does not imply unlimited capacity.

## Optional

- [Source license](https://github.com/fthux/who-arrives/blob/master/LICENSE): AGPL-3.0-only.
- [Country reference data](https://github.com/mledoze/countries): Bundled country data source, licensed under ODbL-1.0.
- [Calling code reference](https://github.com/google/libphonenumber): Calling code data source, licensed under Apache-2.0.
- [Sitemap](https://who-arrives.fthux.com/sitemap.xml): Website page index.
- [Robots policy](https://who-arrives.fthux.com/robots.txt): Website crawler access rules.