Eircode Lookup API

A simple JSON API for resolving Eircodes and Irish addresses to coordinates and a Google Maps link. Distributed exclusively via RapidAPI.

Base URL: https://eircode-api.p.rapidapi.comContent-Type: application/jsonGet an API key on RapidAPI →OpenAPI 3.0 spec

Open source on GitHub

forcequit/eircode-api — MIT licensed

Endpoint

GET/api/eircode?q=<query>

Look up an address or Eircode using a URL query parameter. Best for quick tests and sharing links.

Query parameters

Name	Type	Required	Description
q	string	Yes	Eircode (e.g. `D02 X285`) or address (e.g. `Trinity College Dublin`). 2–200 chars.

curl "https://eircode-api.p.rapidapi.com/api/eircode?q=D02+X285" \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: eircode-api.p.rapidapi.com"

Response

The endpoint returns JSON. ok: true on success, ok: false on failure. HTTP status is 200 on success and 400 on errors (validation, no match, upstream failure).

Success fields (ok: true)

Returned when a result is found.

Field	Type	Description
ok	true	Indicates a successful lookup.
query	string	The original query you submitted.
formattedAddress	string	Human-readable address from Google Maps.
eircode	string \| null	Eircode in `A65 F4E2` format, or `null` if not resolvable.
location.lat	number	Latitude in decimal degrees (WGS84).
location.lng	number	Longitude in decimal degrees (WGS84).
placeId	string	Google Maps Place ID for further API calls.
embedUrl	string	URL ready to drop into an `<iframe>` for a map preview.
tookMs	number	Server-side processing time in milliseconds (includes the upstream geocoding call).

Error fields (ok: false)

Returned with HTTP 400 when a lookup fails.

Field	Type	Description
ok	false	Indicates the lookup failed.
error	string	Human-readable error message.
tookMs	number	Server-side processing time in milliseconds.

Success example

{
  "ok": true,
  "query": "D02 X285",
  "formattedAddress": "Saint Kevin's, Dublin, Co. Dublin, D02 X285, Ireland",
  "eircode": "D02 X285",
  "location": {
    "lat": 53.3320669,
    "lng": -6.255491699999999
  },
  "placeId": "ChIJgclyraMOZ0gRRA_QJFnS6VA",
  "embedUrl": "https://www.google.com/maps/search/?api=1&query=53.3320669,-6.255491699999999&query_place_id=ChIJgclyraMOZ0gRRA_QJFnS6VA",
  "tookMs": 111
}

Error example

{
  "ok": false,
  "error": "No match found in Ireland for that input.",
  "tookMs": 87
}

Self-host (open source)

The API is a small Cloudflare Worker. Run it yourself with your own Google Maps key — no RapidAPI subscription required.

Prerequisites

Bun (or Node.js 18+ with npm)
A free Cloudflare account (only needed to deploy)
A Google Maps API key with Geocoding API and Places API enabled — create one here

Run locally

git clone https://github.com/forcequit/eircode-api.git
cd eircode-api/oss

bun install
cp .dev.vars.example .dev.vars
# edit .dev.vars and set GOOGLE_MAPS_API_KEY=your_key_here

bun run dev
# Worker available at http://localhost:8787
curl "http://localhost:8787/eircode?q=D02+X285"

Deploy to Cloudflare

npx wrangler login
npx wrangler secret put GOOGLE_MAPS_API_KEY
npx wrangler secret put RAPIDAPI_PROXY_SECRET   # optional, locks the endpoint
bun run deploy

Full instructions and the source are on GitHub.

Status codes

Code	Meaning
200	Successful lookup. `ok: true` in the body.
400	Validation error, no match, or upstream geocoding failure. `ok: false`.