Tender awards API: supplier-name search access
Every field on /api/v1/tender_awards is open and unauthenticated
except one: awarded_supplier, the winning bidder's name. For an
unincorporated sole trader, that name is a natural person's own name, so turning
it into bulk, name-searchable data needs a registered, manually-approved API key
-- see the request form.
Every other filter, and every other dataset on this site, needs no key at all.
(a) What awarded_supplier: null means
Every response carries an X-Supplier-Redaction header naming
exactly why the field is null, so you never have to guess:
none-- not redacted; you're authorized and the field is the real value (which can itself still be genuinely blank for some awards).anonymous-- noAuthorizationheader was sent.key-invalid,key-revoked,key-expired,key-unscoped-- a key was sent but rejected, naming why.
This header describes your own auth state, never any specific award's content -- it can't tell you whether one particular row's name is genuinely blank, only whether the field as a whole is being shown to you at all.
(b) Requesting access
POST /ireland/tender-awards/access-requests (JSON: email,
use_case, affirmation) or the plain HTML form linked
above. Real conditions that return 400: use_case must be
10-2000 characters, email must
look like a real address, and affirmation must be true
-- an unaffirmed request is never stored, not stored with a false affirmation.
Every request is reviewed manually; there's no automatic approval and no
guaranteed turnaround, so this isn't a fit for a same-day deadline.
(c) Using a key
# Anonymous -- every field except awarded_supplier, which reads null:
curl "https://statsmapped.com/api/v1/tender_awards?limit=3"
# With an approved key -- awarded_supplier is real, and the supplier= filter unlocks:
curl -H "Authorization: Bearer YOUR_KEY" \
"https://statsmapped.com/api/v1/tender_awards?supplier=NAME"
The server-rendered browse page also takes a key via its own supplier-search form (POST, never a URL parameter, so it can never end up in a browser history or server access log).
(d) Rate limits
120 requests per 5
minutes on /api/v1/tender_awards itself (keyed or anonymous alike);
5 per hour on the access-request endpoint. Both are
reported on every response via X-RateLimit-Limit,
X-RateLimit-Remaining and X-RateLimit-Reset (a Unix
timestamp) -- past the limit, a 429 carries the same headers plus
Retry-After in seconds.
(e) When a key expires or is revoked
supplier= itself returns 401 ("API key has expired"
or "API key has been revoked" -- distinct messages, since you can act
on them differently). On every OTHER call -- an unfiltered listing your key isn't
even actively using for search -- the response still succeeds (200), but
X-Supplier-Redaction switches to key-expired or
key-revoked rather than silently returning to anonymous-
shaped nulls. If you run a scheduled job against this endpoint, that header is
what tells you the credential died instead of your pipeline quietly starting to
record nulls as if nothing were published.
(f) Something's wrong, or your key leaked
Email feedback@statsmapped.com. A leaked or no-longer-needed key can be revoked on request -- it stops working immediately, and re-approval (if you still need access) is a fresh request.