PlanningLeads
← All docs

API & data access

Everything you see in the app is available over a REST API. There are three levels: a free commonwealth API (the public, PII-free planning record - self-serve on any account), the Max data layer (enriched fields, bulk export and webhooks), and the licensed Enterprise layer (the GeoJSON feeds, uncapped bulk and redistribution rights) which is issued to an organisation under an agreement.

1. Get a key

Open Account, then Data API and create a key. The raw key (pl_live_...) is shown once, so copy it then. You can hold up to 10 keys and revoke any of them. A commonwealth key is free on any plan; an enriched key needs Max. The Feed and Custom scopes, which carry the GeoJSON layers and uncapped bulk, come with an Enterprise agreement rather than at checkout: we issue the licence to your organisation, you get a one-time link, and you create the key yourself on this screen. We never see it and cannot re-send it, so if you lose one you revoke it and create another.

A licensed key differs from a self-serve one in two ways worth knowing before you build against it. It counts against the seats on your licence rather than the ten-key limit, and it expires with the licence - your licence page shows the date, the seats in use and your usage over the term.

The full endpoint reference, with every parameter and response shape, is on the API page.

2. Authenticate

Send the key as a Bearer token on every request. The base URL is https://planningleads.ie/api/v1.

curl -H "Authorization: Bearer pl_live_..." \
  "https://planningleads.ie/api/v1/leads?vertical=solar"

The same in Python:

import requests
h = {"Authorization": "Bearer pl_live_..."}
r = requests.get("https://planningleads.ie/api/v1/leads",
                 headers=h, params={"vertical": "solar", "county": "Cork"})
print(r.json()["total"], "leads")

3. Filter (the same options as the app)

Every filter in the leads view is a query parameter, and they combine:

  • vertical - a trade feed (solar, roofing, landscaping, ...).
  • authority or county - a local authority or county.
  • readiness / status - the lifecycle stage.
  • use_class, scale, min_value, min_units - the project shape.
  • q - free-text search.
# On-site major data-centre leads that involve demolition
curl -H "Authorization: Bearer pl_live_..." \
  "https://planningleads.ie/api/v1/leads?use_class=data_centre&scale=major&demolition=1"

4. Page through results

The leads list is page-based: pass page and page_size. To pull a whole filtered set (Max), the export endpoints use a keyset cursor - pass the returned next_cursor back as ?cursor= until it is null (no offset drift on live data).

curl -H "Authorization: Bearer pl_live_..." \
  "https://planningleads.ie/api/v1/export/applications?limit=1000"
# -> { "results": [...], "next_cursor": "...", "count": 1000 }

5. Rate limits

Each response carries X-RateLimit-Limit, -Remaining and -Reset so your client can self-throttle. A commonwealth key allows 600 requests/hour; enriched keys are higher. A 429 means slow down and retry after the reset.

6. Bulk export and webhooks (Max)

  • Bulk export - stream the whole filtered dataset as CSV (/export/applications.csv) or JSON Lines (/export/applications.jsonl), held to a daily row budget on a self-serve seat.
  • Webhooks - have matching new leads pushed to your URL as they file, HMAC-signed (X-PL-Signature), with retries. Configured under Account.

Contact PII is never served over any API scope, and never resold - see Privacy and fair use.

Reference

Browse every endpoint, parameter and response schema: