# Hack Club Geocoder

> A free geocoding and IP geolocation HTTP API run by Hack Club. It turns street addresses into coordinates, coordinates back into addresses, and IP addresses into locations, returning a standardized JSON shape across every endpoint while preserving the complete upstream provider response.

Forward and reverse geocoding are backed by the Google Maps Platform Geocoding API; IP geolocation is backed by IPinfo. Every result is cached in PostgreSQL, so repeated lookups are fast and do not re-bill the upstream provider.

Authentication: every `/v1/` endpoint requires an API key passed as the `key` query parameter, e.g. `?key=your_api_key`. There is no header-based auth. Keys are issued by Hack Club HQ staff - ask in the Hack Club Slack. Each key has its own per-second rate limit (10 requests/second by default); responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers, and exceeding the limit returns HTTP 429 with error code `RATE_LIMIT_EXCEEDED`.

All responses are JSON. Errors use a consistent envelope: `{"error": {"code": "...", "message": "...", "timestamp": "..."}}`. Error codes are `INVALID_API_KEY` (401), `RATE_LIMIT_EXCEEDED` (429), `INVALID_ADDRESS` (400), `INVALID_COORDINATES` (400), `INVALID_IP` (400), `UNSUPPORTED_VERSION` (404), and `EXTERNAL_API_ERROR` (502 when the upstream provider fails, 503 when it is not configured).

Base URL: `https://geocoder.hackclub.com`

## Docs

- [API documentation](https://geocoder.hackclub.com/): The homepage - every endpoint, its parameters, and an example response for each.
- [OpenAPI 3.1 specification](https://geocoder.hackclub.com/openapi.json): Complete machine-readable schema for all public endpoints, including request parameters, response shapes, and error codes.
- [Source code](https://github.com/hackclub/geocoder): The full Go implementation, MIT licensed.

## API endpoints

- [GET /v1/geocode](https://geocoder.hackclub.com/v1/geocode): Geocode a freeform address. Parameters: `address` (required), `key` (required). Returns `lat`, `lng`, `formatted_address`, `state_name`, `state_code`, `country_name`, `country_code`, `backend`, `raw_backend_response`.
- [GET /v1/geocode_structured](https://geocoder.hackclub.com/v1/geocode_structured): Geocode an address supplied as separate components, which is more accurate than a freeform string for form-collected addresses. Parameters: `address_line_1`, `address_line_2`, `city`, `state`, `postal_code`, `country` (all optional, at least one required), `key` (required). Returns the same shape as `/v1/geocode`.
- [GET /v1/reverse_geocode](https://geocoder.hackclub.com/v1/reverse_geocode): Turn coordinates into an address. Parameters: `lat` (required, -90 to 90), `lng` (required, -180 to 180), `key` (required). Returns `lat`, `lng`, `formatted_address`, `address_line_1`, `city`, `state`, `state_full`, `postal_code`, `country_name`, `country_code`, `backend`, `raw_backend_response`.
- [GET /v1/geoip](https://geocoder.hackclub.com/v1/geoip): Locate an IPv4 or IPv6 address. Parameters: `ip` (required), `key` (required). Returns `lat`, `lng`, `ip`, `city`, `region`, `country_name`, `country_code`, `postal_code`, `timezone`, `org`, `backend`, `raw_backend_response`.
- [GET /health](https://geocoder.hackclub.com/health): Service health. No authentication required. Returns `status` (`healthy`, `degraded`, or `unhealthy`), a `services` map, `database_connected`, and `timestamp`. HTTP 200 when healthy or degraded, 503 when unhealthy.

## About

- [Hack Club](https://hackclub.com): The nonprofit that runs this service - a worldwide community of teenage makers and programmers. Legally The Hack Foundation, a 501(c)(3), EIN 81-2908499.
- [Contact](mailto:team@hackclub.com): team@hackclub.com, or +1-855-625-4225.
- [Issue tracker](https://github.com/hackclub/geocoder/issues): Report bugs or request changes to this API.

## Optional

- [Google Geocoding API reference](https://developers.google.com/maps/documentation/geocoding/overview): Documents the fields inside `raw_backend_response` when `backend` is `google_maps_platform_geocoding`.
- [IPinfo API reference](https://ipinfo.io/developers): Documents the fields inside `raw_backend_response` when `backend` is `ipinfo_api`.
- [Hack Club Slack](https://hackclub.com/slack/): Where to ask for an API key or get help.