Awareness Days API

Make your first request

Keep the key on your server or in your tool’s private connection settings. Send it in the Authorization or X-API-Key header. Cookie sessions and query-string keys do not authenticate this API.

curl --fail --get 'https://www.awarenessdays.com/wp-json/ad-data/v1/events' \
  -H "Authorization: Bearer $AD_API_KEY" \
  --data-urlencode 'year=2027' \
  --data-urlencode 'q=community' \
  --data-urlencode 'per_page=25'

const params = new URLSearchParams({ year: '2027', q: 'community', per_page: '25' });
const response = await fetch('https://www.awarenessdays.com/wp-json/ad-data/v1/events?' + params, {
  headers: { Authorization: `Bearer ${process.env.AD_API_KEY}` }
});
if (!response.ok) throw new Error(`Awareness Days HTTP ${response.status}`);
const { items, total, page, pages } = await response.json();
console.log({ total, page, pages, items });

import json, os
from urllib.parse import urlencode
from urllib.request import Request, urlopen

params = urlencode({'year': '2027', 'q': 'community', 'per_page': 25})
request = Request('https://www.awarenessdays.com/wp-json/ad-data/v1/events?' + params,
    headers={'Authorization': 'Bearer ' + os.environ['AD_API_KEY']})
with urlopen(request, timeout=30) as response:
    data = json.load(response)
print(data['total'], data['page'], data['pages'], data['items'])

Endpoints

Choose your records

Filters are q, year, category, region, type, tier, channel, from, to, sort and order. Query /facets for exact labels before filtering by topic or region.

• year is an available year or all.
• from and to use YYYY-MM-DD. Events match when their date range overlaps the requested period.
• q searches names and context and allows up to 120 characters.
• page starts at 1; per_page is 25 or 50.
• sort is start, end, title or days; order is asc or desc.

Read every page and reconcile unique occurrence keys with total before describing a result as complete. Source snapshots and totals should remain consistent across pages. Use a complete filtered export when you need a file.

Response fields

/events returns items, total, page, pages, per_page, filters, facets, years, sources, provenance, quota. /event/{key} returns event, sources, quota.

{
    "key": "illustrative-event-2027",
    "start": "2027-05-12",
    "end": "2027-05-12",
    "title": "Example Community Day",
    "categories": "Community",
    "region": "UK",
    "context": "An invented record to show the response format.",
    "guide": ""
}

The example is invented to show field names. Actual records also include duration, event type, priority, suggested channels, references and available published metadata. A post ID is not the occurrence key: recurring events can have different occurrences by year.

Dates are all-day calendar dates. Missing context is unknown. Image URLs and credits describe published source material and do not grant new image rights.

Limits and errors

All keys on one account share 1,000 requests per UTC day and 60 requests per minute. Up to three active keys are available. Key rotation does not reset usage. Authenticated invalid requests count toward the allowance.

HTTP 400 means invalid input; 401 means a missing, invalid or revoked header key; 403 means inactive data access; 404 means the occurrence was not found; 429 means the shared allowance is exhausted; 503 means the source or storage is temporarily unavailable.

Inspect Retry-After, the X-RateLimit-* response headers and JSON quota. Reset values are Unix UTC seconds. Do not silently replace a failed live request with example records.

Sources and updates

Records come from published Awareness Days events, existing date rules and saved member snapshots. This is not a fresh organiser-by-organiser audit. /status reports available years and source timestamps; these describe available snapshots, not a promise every organiser was just checked.

Link to the event guide when presenting a date and check it before publishing a campaign. CSV and ICS are file exports. Most calendar apps cannot attach API headers; these machine endpoints are not private calendar subscription URLs.