Skip to content
iGregulator docs

Per-jurisdiction scraper freshness

GET
/v1/health/coverage

Public endpoint. Exposes the age of the most recent successful scraper run per jurisdiction so consumers can see the freshness guarantee substantiated without provisioning a key.

Freshness SLA — UKGC (direct ZIP download) is considered fresh while age_hours < 24; scraped sources (MGA, CW, KH) while age_hours < 48. status is healthy when every jurisdiction meets its SLA, degraded when any is stale.

Rate limit: 10 requests / IP / hour (unauthenticated).

Each jurisdiction also carries a domain_coverage object: the share of consumer-facing operators (license-type-normative subset) that have ≥1 domain in our DB. See coverage methodology for the per-jurisdiction filter and reading guidance.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Coverage freshness map.

object
status
required
string
Allowed values: healthy degraded
overall_freshness_sla
required
string
jurisdictions
required
object
key
additional properties
object
last_successful_scrape
string format: date-time
nullable
age_hours
integer
nullable
fresh
boolean
nullable
sla_hours
required
integer
record_count
required
integer
domain_coverage

Domain-coverage metric scoped to operators where domain disclosure is normative for their license type. See https://igregulator.io/docs/coverage-methodology/

object
operators_with_domain
integer
normative_operators
integer
coverage_pct
integer
nullable
reason
string
timestamp
required
string format: date-time

429

Section titled “429 ”

Rate limit reached. Public endpoints: 10 req / IP / hour. Authenticated: per plan tier. Retry after the window surfaced in X-RateLimit-Reset.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
}
{
  "error": "API key has been revoked",
  "code": "auth_revoked",
  "details": {
    "reason": "api_key_revoked",
    "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
  }
}

Headers

Section titled “Headers ”
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer
X-RateLimit-Reset
integer

Unix epoch seconds.

X-Upgrade-URL
string format: uri

500

Section titled “500 ”

Unexpected server error.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
}
{
  "error": "API key has been revoked",
  "code": "auth_revoked",
  "details": {
    "reason": "api_key_revoked",
    "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
  }
}