Public API Docs

AgentCompare.ie public endpoints

This page explains the public endpoints we intentionally expose for agent discovery. The machine-readable catalog lives at /.well-known/api-catalog.

Admin-only routes and disabled Google Places endpoints are left out on purpose so agents only discover APIs that are safe and genuinely usable from the public web.

How to use this section

Each endpoint below links to a machine-readable JSON description.
Request and response examples mirror the live route handlers in this codebase.
Rate limits shown here describe the default server settings in the current app.

GET

PPR Search

Returns recent sale records that match a free-text address query, with optional county and year filters.

GET

/api/ppr/search

Summary

Search Irish property sale records stored in the local PPR dataset.

Query parameters

Name	Type	Required	Notes
q	string	Yes	Free-text address query. Minimum 2 characters.
county	string	No	County filter. Only Dublin is available right now.
year	number	No	Sale year filter. Supported values are 2025 and 2026.
limit	number	No	Page size. Defaults to 25 and is capped server-side.
offset	number	No	Pagination offset. Defaults to 0.

Response examples

200 • Matching sale records.

application/json

{
  "results": [
    {
      "id": "sale_123",
      "address": "12 Seaview Park, Blackrock, Co Dublin",
      "county": "Dublin",
      "sale_date": "2026-02-14",
      "sale_date_display": "14/02/2026",
      "sale_price": 685000,
      "sale_price_label": "VAT-inclusive",
      "property_type": "Existing / Second-Hand Dwelling house /Apartment",
      "vat_exclusive": false,
      "not_full_market_price": false,
      "sale_price_vat_inclusive": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10,
  "hasMore": false,
  "meta": {
    "query": "Blackrock",
    "county": "Dublin",
    "year": 2026,
    "timestamp": "2026-04-19T09:00:00.000Z"
  }
}

400 • Validation error for query, county, or year filters.

application/json

{
  "error": "Query must be at least 2 characters."
}

GET

Geocode

Returns a formatted address, coordinates, Eircode, and routing key for a supplied address, Google place ID, or latitude/longitude pair.

GET

/api/geocode

Summary

Resolve an address, place ID, or coordinates into location details.

Query parameters

Name	Type	Required	Notes
address	string	No	Postal address to geocode.
placeId	string	No	Google Place ID to resolve.
lat	number	No	Latitude for reverse geocoding.
lng	number	No	Longitude for reverse geocoding.
resultType	string	No	Optional reverse-geocode result type hint.

Response examples

200 • Resolved location data.

application/json

{
  "formattedAddress": "Blackrock, County Dublin, Ireland",
  "location": {
    "lat": 53.3015,
    "lng": -6.1778
  },
  "postalCode": "A94",
  "eircode": "A94",
  "routingKey": "A94"
}

429 • Rate limit exceeded.

application/json

{
  "error": "Too many geocode lookups. Please wait and try again."
}

POST

Resolve Eircode

Accepts a full Irish Eircode and returns a formatted address, location coordinates, routing key, and county when the lookup can be verified.

POST

/api/location/resolve-eircode

Summary

Verify and resolve an Irish Eircode into address and map coordinates.

JSON body

Field	Type	Required	Notes
eircode	string	Yes	Full Irish Eircode, for example A65 F4E2.

Response examples

200 • Verified Eircode lookup result.

application/json

{
  "formattedAddress": "Main Street, Bray, Co. Wicklow, Ireland",
  "location": {
    "lat": 53.2022,
    "lng": -6.0983
  },
  "eircode": "A98 F8F2",
  "routingKey": "A98",
  "county": "Wicklow"
}

400 • Invalid JSON body or invalid Eircode format.

application/json

{
  "error": "Enter a full Eircode like A65 F4E2."
}

404 • The Eircode could not be verified.

application/json

{
  "error": "We couldn't verify that Eircode yet. Please request a concierge audit for now."
}

POST

Valuation Estimate

Builds a valuation estimate using nearby PPR sales after geocoding an address, Google place ID, or supplied coordinates.

POST

/api/valuation/estimate

Summary

Estimate a property value from address or coordinate input.

JSON body

Field	Type	Required	Notes
address	string	No	Address to geocode before running the valuation.
placeId	string	No	Google Place ID to geocode before running the valuation.
locationLat	number	No	Latitude when coordinates are already known.
locationLng	number	No	Longitude when coordinates are already known.
formattedAddress	string	No	Optional display address when coordinates are supplied directly.
propertyType	string (detached, semi-detached, terraced, bungalow, apartment, site)	No	Optional property type hint.

Response examples

200 • Valuation estimate with comparable sales summary.

application/json

{
  "address": "12 Seaview Park, Blackrock, Co Dublin",
  "location": {
    "lat": 53.3015,
    "lng": -6.1778
  },
  "estimate": {
    "low": 640000,
    "mid": 685000,
    "high": 730000
  },
  "confidence": "medium",
  "comps": [
    {
      "id": "sale_123",
      "address": "4 Example Avenue, Blackrock, Co Dublin",
      "sale_price": 690000,
      "sale_date": "2026-01-18"
    }
  ],
  "stats": {
    "compsCount": 1,
    "radiusKm": 1.5,
    "monthsLookback": 24
  }
}

400 • Missing address input or invalid request body.

application/json

{
  "error": "Address, placeId, or coordinates are required."
}

429 • Rate limit exceeded.

application/json

{
  "error": "Too many valuation checks. Please wait and try again."
}