Active Travel Tracker API
Reference for every endpoint a council or school API key can call.
Download the OpenAPI specification (openapi.yaml, version 1.0.0)
Every endpoint here is called with an API key: a council- or school-scoped bearer token that a Council Administrator issues from API keys in the console.
For how to issue and handle a key, see Export your data.
API keys
A key is scoped to one council or one school and is read-only:
it holds the VIEWER role, so it can never satisfy a write or admin check.
Every endpoint a key can reach is a GET. The scope is enforced per
resource, and a request outside it returns 403 (or 404 when the
resource does not exist), never data.
- A council key covers that council and everything under it: its schools, classes, pupils and clusters.
- A school key covers that school and everything under it. It also covers the dashboard of a cluster its school belongs to, which is the one place a school-scoped caller reads beyond its own school.
- A key that is not recognised is
401. It does not fall back to a session.
The endpoints under Roster and Pupil statistics are the ones the
classroom and pupil screens use, and a key reaches them because they
authorise any caller with a read grant over the resource. They are
documented because they are reachable, not because they are the intended
integration surface. They return pupil-level data (pseudonymous display
names, per-pupil streaks and badges). Prefer /api/v1/export and the
dashboard endpoints for reporting, which are aggregate-only.
Dates
from and to are YYYY-MM-DD and are Dublin school days, both ends
inclusive. A malformed date is 400. When both are omitted a dashboard
covers today only; /api/v1/export defaults to the last 30 days.
Travel modes
WALK, CYCLE, SCOOTER, PARK_STRIDE, BUS, RAIL, CAR_SHARE,
CAR. The active-travel rate counts every mode except CAR.
Data lifetime
These endpoints read live JourneyLog rows. After the retention job has
removed the pupil-level rows of an ended academic year
(RETENTION_ROLLUP_DELETE=true), that year's data is only in the
JourneyAggregate archive and is not returned by these endpoints.
Authentication
ApiKey- http bearer. A council- or school-scoped, read-only key from API keys in the
console. Shown once at creation; only a hash is stored. Send as
Authorization: Bearer <key>.
Base URL: https://tapin.ie
Export
The programmatic extract. Aggregate-only.
GET /api/v1/export
Journey counts by date, school, class and mode
The recurring-extract endpoint. One row per date, class and mode, with a count of journeys. No pupil appears in the response.
Pull the morning after: journeys can be amended until 23:59 on the day
they were recorded. Re-pulling a past period returns the same figures.
Pass explicit from and to, because the 30-day default moves.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
scope | query | string | Defaults to the key's own scope. Case-insensitive. school council |
id | query | string | The school or council id. Defaults to the key's own scope id. |
from | query | string (date) | First day, inclusive. Defaults to 30 days ago. |
to | query | string (date) | Last day, inclusive. Defaults to today. |
Responses
200 Aggregated counts.
metaobject requiredscopestring requiredschoolcouncilidstring requiredfromstring (date) requiredtostring (date) requiredtotalRecordsinteger required — Number of rows indata, not the number of journeys.notestring required
dataarray of object requireddatestring (date) requiredschoolstring requiredclassNamestring requiredyearGroupstring requiredmodestring requiredWALKCYCLESCOOTERPARK_STRIDEBUSRAILCAR_SHARECARcountinteger required
{
"meta": {
"scope": "council",
"id": "clx0council",
"from": "2026-09-01",
"to": "2026-09-30",
"totalRecords": 1,
"note": "Data is aggregated by date/school/class/mode. No individual student identifiers are included."
},
"data": [
{
"date": "2026-09-01",
"school": "St. Brigid's NS",
"className": "3rd Class A",
"yearGroup": "3rd",
"mode": "WALK",
"count": 18
}
]
}400 scope is not school or council, or from/to is not a YYYY-MM-DD date.
errorstring required
401 No key, or the key is not valid. Session cookies are not accepted here.
errorstring required
403 The key does not cover the requested school or council.
errorstring required
404 The school or council does not exist.
errorstring required
Dashboards
The figures behind the console dashboards. Aggregate-only.
GET /api/dashboard/council
Council dashboard
Active-travel figures for a whole council over a period. Requires a
council key for this council; a school key gets 403.
Despite the ...Today field names, the figures cover the whole period
selected with from/to.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
councilId | query | string required | |
from | query | string (date) | First day, inclusive. Defaults to today. |
to | query | string (date) | Last day, inclusive. Defaults to today. |
Responses
200 The council's figures.
totalStudentsinteger requiredoverallActiveRateinteger required — Whole-number percentage.schoolCountinteger requiredyearlyTrendarray of object required — One entry per month with any journeys, oldest first.monthstring requiredactivePctinteger requiredtotalJourneysinteger required
primaryVsSecondaryobject requiredprimaryobject requiredschoolCountinteger requiredtotalStudentsinteger requiredactiveRateinteger required
secondaryobject requiredschoolCountinteger requiredtotalStudentsinteger requiredactiveRateinteger required
topMoversarray of object required — The five schools with the highest active rate.schoolNamestring requiredschoolNameAltstring, nullable requiredactiveRateinteger requiredlogsTodayinteger required — Journeys in the period.
councilKpisobject requiredtotalStudentsinteger requiredoverallActiveRateinteger requiredschoolCountinteger requiredco2SavedThisYearnumber required — Kilograms, modelled from journey counts.kmWalkedThisYearnumber required — Modelled from journey counts.kmCycledThisYearnumber required — Modelled from journey counts.totalJourneysThisYearinteger required
councilModeMixobject required — Journey count per travel mode. Modes with no journeys are absent.<key>integer
schoolLocationsarray of object requirednamestring requirednameAltstring, nullable required — The Irish-language name.latitudenumber requiredlongitudenumber requiredstudentCountinteger requiredactiveRateinteger required — Whole-number percentage.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
GET /api/dashboard/usage
Council usage report
Adoption rather than travel: which schools and classes are checking in, which have gone quiet, and a week-by-week series. Requires a council key. Counts are check-ins, not travel modes.
The period is compared with the window of the same length immediately
before it (summary.prev).
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
councilId | query | string required | |
from | query | string (date) | First day, inclusive. Defaults to today. |
to | query | string (date) | Last day, inclusive. Defaults to today. |
Responses
200 The usage report.
summaryobject requiredtotalSchoolsinteger requiredactiveSchoolsinteger required — Schools with a check-in in the period.everSchoolsinteger required — Schools that have ever checked in.newSchoolsAddedinteger required — Schools created in the period.newSchoolsStartedinteger required — Schools whose first ever check-in was in the period.totalClassesinteger required — Classes of the current academic year.activeClassesinteger requiredeverClassesinteger requirednewClassesStartedinteger requiredtotalStudentsinteger requiredtotalCheckInsinteger requiredactiveDaysinteger required — Distinct days with any check-in.prevobject required — The same measures for the window of equal length immediately before the period.activeSchoolsinteger requiredactiveClassesinteger requiredcheckInsinteger required
weeklyarray of object required — Monday-anchored weeks, zero-filled.weekOfstring (date) requiredcheckInsinteger requiredschoolsinteger required — Distinct schools that checked in.classesinteger required — Distinct classes that checked in.
schoolsarray of object requiredidstring requirednamestring requirednameAltstring, nullable requiredtypestring requiredPRIMARYSECONDARYaddedAtstring (date) requiredaddedInPeriodboolean requiredstartedInPeriodboolean requiredstagestring required — Where the school is in getting going.activehas check-ins in the period;quiethas checked in before but not in the period;notStartedhas classes but has never checked in;noClasseshas no classes this year.newis reserved and not currently produced.newnoClassesnotStartedquietactiveclassesinteger requiredactiveClassesinteger requiredstudentsinteger requiredcheckInsinteger requiredactiveDaysinteger requiredlastCheckInstring (date), nullable required
quietClassesarray of object required — Every class with no check-ins in the period.idstring requiredschoolIdstring requiredschoolNamestring requiredschoolNameAltstring, nullable requirednamestring requiredstudentsinteger requiredlastCheckInstring (date), nullable required
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
GET /api/dashboard/cluster
Cluster dashboard
Comparison across the schools in a cluster. A council key for the cluster's council can read it, and so can a school key for a school that is a member of the cluster.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
clusterId | query | string required | |
from | query | string (date) | First day, inclusive. Defaults to today. |
to | query | string (date) | Last day, inclusive. Defaults to today. |
Responses
200 The cluster's figures.
schoolSummariesarray of object requiredschoolNamestring requiredschoolNameAltstring, nullable requiredstudentCountinteger requiredactiveRateinteger requiredrankinteger required — 1 is the highest active rate.modeMixobject required — Journey count per travel mode. Modes with no journeys are absent.<key>integer
clusterKpisobject requiredtotalStudentsinteger requiredcheckedInTodayinteger required — Journeys in the period.overallActiveRateinteger requiredschoolCountinteger requiredco2SavedThisTermnumber required — Kilograms, modelled.
weeklyTrendarray of object required — The last 7 days, independent offrom/to. Days with no journeys are absent.datestring (date) requiredactivePctinteger required
trendarray of object required — Monday-anchored weekly buckets across the selected period.weekStartstring (date) requiredactivePctinteger required
clusterModeMixobject required — Journey count per travel mode. Modes with no journeys are absent.<key>integer
schoolLocationsarray of object requirednamestring requirednameAltstring, nullable required — The Irish-language name.latitudenumber requiredlongitudenumber requiredstudentCountinteger requiredactiveRateinteger required — Whole-number percentage.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
GET /api/dashboard/school
School dashboard
A school's figures for a period, with a per-class breakdown. A council key for the school's council, or a school key for this school.
weeklyTrend and each class's trend always cover the last 10 school
weekdays, whatever from/to say.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
schoolId | query | string required | |
from | query | string (date) | First day, inclusive. Defaults to today. |
to | query | string (date) | Last day, inclusive. Defaults to today. |
Responses
200 The school's figures.
schoolNamestring, nullable requiredschoolNameAltstring, nullable requiredkpisobject requiredcheckedIninteger required — Check-ins by active pupils, averaged over the days the school logged anything. Read it againsttotal.totalinteger required — Active pupils on the roll.activePctinteger requiredco2Savednumber required — Kilograms, modelled.kmWalkednumber required — Modelled.kmCyclednumber required — Modelled.
todayMixobject required — Mode mix across the selected period (the name is historical).<key>integer
classSummariesarray of object required — Highest active rate first.idstring requirednamestring requiredyearGroupstring requiredstudentCountinteger requiredcheckedIninteger requiredactiveRateinteger requiredtopModestring, nullable requiredWALKCYCLESCOOTERPARK_STRIDEBUSRAILCAR_SHARECARmodeCountsobject required — Journey count per travel mode. Modes with no journeys are absent.<key>integer
trendarray of integer required — Active percentage for each of the last 10 school weekdays, oldest first. 0 where there were no journeys.
weeklyTrendarray of object required — The last 10 school weekdays, oldest first.datestring (date) requiredactivePctinteger required
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
Roster
Schools' classes and pupils. Pupil-level, read-only for a key.
GET /api/classes
A school's classes
The classes of one academic year, ordered by year group. Defaults to the
current academic year. An unknown or empty year returns [], not an
error and not another year's classes.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
schoolId | query | string required | |
academicYearId | query | string | A past year's roster. Defaults to the current academic year. |
Responses
200 The classes.
idstring requirednamestring requiredyearGroupstring requiredstudentCountinteger required — Active pupils on the roll.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
GET /api/classes/{classId}
One class, with its school and council branding
Used by the classroom board to theme itself. The class's parentCode is
never returned to an API key; only a signed-in session gets it.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
classId | path | string required |
Responses
200 The class.
idstring requirednamestring requiredyearGroupstring requiredschoolIdstring requiredschoolobject requirednamestring required
featuresobject required — The council's resolved feature switches, by feature name.<key>boolean
brandingobject requiredaccentColorstring, nullable requiredlogoUrlstring, nullable requiredbannerobject, nullable required — The council's board banner, if it has one.srcstring required — Path of the banner image.altstring required
charactersarray of string, nullable required — Image paths of the council's check-in characters, if it has them.
councilSlugstring, nullable required — Null unless the council has the privacy-notice feature on and has published a notice.
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
GET /api/students
A class's pupils and what each logged today
Active pupils of one class, ordered by display name, with today's travel
mode (a Dublin school day) or null if they have not checked in.
Pupil-level. Display names are pseudonymous (generated animal names,
or Pupil-xxxx once anonymised), but this is not an aggregate endpoint.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
classId | query | string required |
Responses
200 The pupils.
idstring requireddisplayNamestring requiredtodayModestring, nullable requiredWALKCYCLESCOOTERPARK_STRIDEBUSRAILCAR_SHARECAR
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
GET /api/students/{id}
One pupil's record
The pupil row with its class. Pupil-level. Only active pupils are
found; a deactivated pupil is 404.
The response also carries statsToken, a short-lived capability scoped
to this one pupil, which the accountless /journey page uses against
the Pupil statistics endpoints. It is null when no signing secret is
configured.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id | path | string required |
Responses
200 The pupil.
idstring requireddisplayNamestring requiredclassIdstring requiredactiveboolean required — Always true; inactive pupils are not found.deactivatedAtstring (date-time), nullablecreatedAtstring (date-time) requiredclassobject required — The pupil's class row, with the size of its roll.idstring requirednamestring requiredschoolIdstring requiredacademicYearIdstring requiredyearGroupstring requiredparentCodestring, nullable — The class's parent share-link code.createdAtstring (date-time) required_countobject requiredstudentsinteger — Active pupils on the roll.
statsTokenstring, nullable required — Short-lived token scoped to this pupil, for the Pupil statistics endpoints (?statsToken=).
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
Pupil statistics
Per-pupil streaks and badges, plus today's class check-ins.
GET /api/journey
Today's check-ins for a class
Each pupil's journey recorded today (a Dublin school day), one entry per
pupil who has checked in. Pupil-level. Writes to this path (POST,
DELETE) are authorised by the school access code only; a key cannot
make them.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
classId | query | string required |
Responses
200 Today's check-ins.
studentIdstring requiredmodestring requiredWALKCYCLESCOOTERPARK_STRIDEBUSRAILCAR_SHARECARtimestring (date-time) required — When the check-in was recorded.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
GET /api/journey/streak
One pupil's streak and active days
Pupil-level. The streak is consecutive days ending today on which the pupil logged an active mode, looking back at most 365 days.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
studentId | query | string required |
Responses
200 The pupil's statistics.
studentIdstring requiredactiveDaysinteger required — Active journeys logged, all time.streakinteger requiredactiveDaysThisMonthinteger required — Active days in the current Dublin calendar month.monthlyTargetinteger required — Active days needed in a month for the Monthly Hero badge.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
500 Unexpected failure.
errorstring required
GET /api/journey/badges
One pupil's badges
Pupil-level. Newest first.
Authentication: ApiKey
Parameters
| Name | In | Type | Description |
|---|---|---|---|
studentId | query | string required |
Responses
200 The pupil's badges.
idstring requiredtypestring requiredFIRST_ACTIVE_DAYSTREAK_5STREAK_10STREAK_20CHALLENGE_WINNERMONTHLY_HEROawardedAtstring (date-time) required
400 A required parameter is missing, or a date is not YYYY-MM-DD.
errorstring required
401 No credential, or it is not valid.
errorstring required
403 The credential does not cover this resource.
errorstring required
404 The resource does not exist.
errorstring required
Still stuck? Email our support team.