Active Travel Logger Help

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.

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

NameInTypeDescription
scopequerystringDefaults to the key's own scope. Case-insensitive. school council
idquerystringThe school or council id. Defaults to the key's own scope id.
fromquerystring (date)First day, inclusive. Defaults to 30 days ago.
toquerystring (date)Last day, inclusive. Defaults to today.

Responses

200 Aggregated counts.
application/json
  • meta object required
    • scope string required
      school council
    • id string required
    • from string (date) required
    • to string (date) required
    • totalRecords integer required — Number of rows in data, not the number of journeys.
    • note string required
  • data array of object required
    • date string (date) required
    • school string required
    • className string required
    • yearGroup string required
    • mode string required
      WALK CYCLE SCOOTER PARK_STRIDE BUS RAIL CAR_SHARE CAR
    • count integer 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.
application/json
  • error string required
401 No key, or the key is not valid. Session cookies are not accepted here.
application/json
  • error string required
403 The key does not cover the requested school or council.
application/json
  • error string required
404 The school or council does not exist.
application/json
  • error string 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

NameInTypeDescription
councilIdquerystring required
fromquerystring (date)First day, inclusive. Defaults to today.
toquerystring (date)Last day, inclusive. Defaults to today.

Responses

200 The council's figures.
application/json
  • totalStudents integer required
  • overallActiveRate integer required — Whole-number percentage.
  • schoolCount integer required
  • yearlyTrend array of object required — One entry per month with any journeys, oldest first.
    • month string required
    • activePct integer required
    • totalJourneys integer required
  • primaryVsSecondary object required
    • primary object required
      • schoolCount integer required
      • totalStudents integer required
      • activeRate integer required
    • secondary object required
      • schoolCount integer required
      • totalStudents integer required
      • activeRate integer required
  • topMovers array of object required — The five schools with the highest active rate.
    • schoolName string required
    • schoolNameAlt string, nullable required
    • activeRate integer required
    • logsToday integer required — Journeys in the period.
  • councilKpis object required
    • totalStudents integer required
    • overallActiveRate integer required
    • schoolCount integer required
    • co2SavedThisYear number required — Kilograms, modelled from journey counts.
    • kmWalkedThisYear number required — Modelled from journey counts.
    • kmCycledThisYear number required — Modelled from journey counts.
    • totalJourneysThisYear integer required
  • councilModeMix object required — Journey count per travel mode. Modes with no journeys are absent.
    • <key> integer
  • schoolLocations array of object required
    • name string required
    • nameAlt string, nullable required — The Irish-language name.
    • latitude number required
    • longitude number required
    • studentCount integer required
    • activeRate integer required — Whole-number percentage.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
councilIdquerystring required
fromquerystring (date)First day, inclusive. Defaults to today.
toquerystring (date)Last day, inclusive. Defaults to today.

Responses

200 The usage report.
application/json
  • summary object required
    • totalSchools integer required
    • activeSchools integer required — Schools with a check-in in the period.
    • everSchools integer required — Schools that have ever checked in.
    • newSchoolsAdded integer required — Schools created in the period.
    • newSchoolsStarted integer required — Schools whose first ever check-in was in the period.
    • totalClasses integer required — Classes of the current academic year.
    • activeClasses integer required
    • everClasses integer required
    • newClassesStarted integer required
    • totalStudents integer required
    • totalCheckIns integer required
    • activeDays integer required — Distinct days with any check-in.
    • prev object required — The same measures for the window of equal length immediately before the period.
      • activeSchools integer required
      • activeClasses integer required
      • checkIns integer required
  • weekly array of object required — Monday-anchored weeks, zero-filled.
    • weekOf string (date) required
    • checkIns integer required
    • schools integer required — Distinct schools that checked in.
    • classes integer required — Distinct classes that checked in.
  • schools array of object required
    • id string required
    • name string required
    • nameAlt string, nullable required
    • type string required
      PRIMARY SECONDARY
    • addedAt string (date) required
    • addedInPeriod boolean required
    • startedInPeriod boolean required
    • stage string required — Where the school is in getting going. active has check-ins in the period; quiet has checked in before but not in the period; notStarted has classes but has never checked in; noClasses has no classes this year. new is reserved and not currently produced.
      new noClasses notStarted quiet active
    • classes integer required
    • activeClasses integer required
    • students integer required
    • checkIns integer required
    • activeDays integer required
    • lastCheckIn string (date), nullable required
  • quietClasses array of object required — Every class with no check-ins in the period.
    • id string required
    • schoolId string required
    • schoolName string required
    • schoolNameAlt string, nullable required
    • name string required
    • students integer required
    • lastCheckIn string (date), nullable required
400 A required parameter is missing, or a date is not YYYY-MM-DD.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
clusterIdquerystring required
fromquerystring (date)First day, inclusive. Defaults to today.
toquerystring (date)Last day, inclusive. Defaults to today.

Responses

200 The cluster's figures.
application/json
  • schoolSummaries array of object required
    • schoolName string required
    • schoolNameAlt string, nullable required
    • studentCount integer required
    • activeRate integer required
    • rank integer required — 1 is the highest active rate.
    • modeMix object required — Journey count per travel mode. Modes with no journeys are absent.
      • <key> integer
  • clusterKpis object required
    • totalStudents integer required
    • checkedInToday integer required — Journeys in the period.
    • overallActiveRate integer required
    • schoolCount integer required
    • co2SavedThisTerm number required — Kilograms, modelled.
  • weeklyTrend array of object required — The last 7 days, independent of from/to. Days with no journeys are absent.
    • date string (date) required
    • activePct integer required
  • trend array of object required — Monday-anchored weekly buckets across the selected period.
    • weekStart string (date) required
    • activePct integer required
  • clusterModeMix object required — Journey count per travel mode. Modes with no journeys are absent.
    • <key> integer
  • schoolLocations array of object required
    • name string required
    • nameAlt string, nullable required — The Irish-language name.
    • latitude number required
    • longitude number required
    • studentCount integer required
    • activeRate integer required — Whole-number percentage.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
schoolIdquerystring required
fromquerystring (date)First day, inclusive. Defaults to today.
toquerystring (date)Last day, inclusive. Defaults to today.

Responses

200 The school's figures.
application/json
  • schoolName string, nullable required
  • schoolNameAlt string, nullable required
  • kpis object required
    • checkedIn integer required — Check-ins by active pupils, averaged over the days the school logged anything. Read it against total.
    • total integer required — Active pupils on the roll.
    • activePct integer required
    • co2Saved number required — Kilograms, modelled.
    • kmWalked number required — Modelled.
    • kmCycled number required — Modelled.
  • todayMix object required — Mode mix across the selected period (the name is historical).
    • <key> integer
  • classSummaries array of object required — Highest active rate first.
    • id string required
    • name string required
    • yearGroup string required
    • studentCount integer required
    • checkedIn integer required
    • activeRate integer required
    • topMode string, nullable required
      WALK CYCLE SCOOTER PARK_STRIDE BUS RAIL CAR_SHARE CAR
    • modeCounts object required — Journey count per travel mode. Modes with no journeys are absent.
      • <key> integer
    • trend array of integer required — Active percentage for each of the last 10 school weekdays, oldest first. 0 where there were no journeys.
  • weeklyTrend array of object required — The last 10 school weekdays, oldest first.
    • date string (date) required
    • activePct integer required
400 A required parameter is missing, or a date is not YYYY-MM-DD.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
schoolIdquerystring required
academicYearIdquerystringA past year's roster. Defaults to the current academic year.

Responses

200 The classes.
application/json
  • id string required
  • name string required
  • yearGroup string required
  • studentCount integer required — Active pupils on the roll.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
classIdpathstring required

Responses

200 The class.
application/json
  • id string required
  • name string required
  • yearGroup string required
  • schoolId string required
  • school object required
    • name string required
  • features object required — The council's resolved feature switches, by feature name.
    • <key> boolean
  • branding object required
    • accentColor string, nullable required
    • logoUrl string, nullable required
    • banner object, nullable required — The council's board banner, if it has one.
      • src string required — Path of the banner image.
      • alt string required
    • characters array of string, nullable required — Image paths of the council's check-in characters, if it has them.
  • councilSlug string, 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.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
classIdquerystring required

Responses

200 The pupils.
application/json
  • id string required
  • displayName string required
  • todayMode string, nullable required
    WALK CYCLE SCOOTER PARK_STRIDE BUS RAIL CAR_SHARE CAR
400 A required parameter is missing, or a date is not YYYY-MM-DD.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
idpathstring required

Responses

200 The pupil.
application/json
  • id string required
  • displayName string required
  • classId string required
  • active boolean required — Always true; inactive pupils are not found.
  • deactivatedAt string (date-time), nullable
  • createdAt string (date-time) required
  • class object required — The pupil's class row, with the size of its roll.
    • id string required
    • name string required
    • schoolId string required
    • academicYearId string required
    • yearGroup string required
    • parentCode string, nullable — The class's parent share-link code.
    • createdAt string (date-time) required
    • _count object required
      • students integer — Active pupils on the roll.
  • statsToken string, nullable required — Short-lived token scoped to this pupil, for the Pupil statistics endpoints (?statsToken=).
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
classIdquerystring required

Responses

200 Today's check-ins.
application/json
  • studentId string required
  • mode string required
    WALK CYCLE SCOOTER PARK_STRIDE BUS RAIL CAR_SHARE CAR
  • time string (date-time) required — When the check-in was recorded.
400 A required parameter is missing, or a date is not YYYY-MM-DD.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string 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

NameInTypeDescription
studentIdquerystring required

Responses

200 The pupil's statistics.
application/json
  • studentId string required
  • activeDays integer required — Active journeys logged, all time.
  • streak integer required
  • activeDaysThisMonth integer required — Active days in the current Dublin calendar month.
  • monthlyTarget integer 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.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required
500 Unexpected failure.
application/json
  • error string required

GET /api/journey/badges

One pupil's badges

Pupil-level. Newest first.

Authentication: ApiKey

Parameters

NameInTypeDescription
studentIdquerystring required

Responses

200 The pupil's badges.
application/json
  • id string required
  • type string required
    FIRST_ACTIVE_DAY STREAK_5 STREAK_10 STREAK_20 CHALLENGE_WINNER MONTHLY_HERO
  • awardedAt string (date-time) required
400 A required parameter is missing, or a date is not YYYY-MM-DD.
application/json
  • error string required
401 No credential, or it is not valid.
application/json
  • error string required
403 The credential does not cover this resource.
application/json
  • error string required
404 The resource does not exist.
application/json
  • error string required

Still stuck? Email our support team.