Skip to main content
A group key reads one group’s members, events and badges. A district, county, area, region, country or the national team gets a different kind of key: a district or area key. It reads totals for the groups below it, and the names of those groups. It never reads a young person, a parent or anything typed as free text.

​
Create a key

A district or area admin creates the key in the district’s Settings → Integrations → API keys. Choose one or both scopes: A district or area key cannot hold a group scope, and a group key cannot hold these. Each kind of key gets 403 with the code insufficient_scope on the other kind’s endpoints. GET /me works for both: its group.tier is group for a group key, and the level (district, county and so on) for a district or area key.

​
Which groups you see

You see a group only when it shares data with you, and every level between it and you shares too. A group that does not share, a group under a district that has stopped sharing with your county, and a deleted group are never listed, and their figures never appear in a row of their own. childId narrows GET /nodes/metrics to one group or node below yours. An id you cannot see answers 404, the same as an id that does not exist.

​
How fresh the totals are

The totals are built each night. Each row says which night (day) and when its oldest figure was counted (asOf).
  • A group that stops sharing with you leaves the per-group rows at once. Its young people stay inside your own total until the next build, so within 24 hours.
  • A group that moves to another district shows in both districts’ totals the same way: within 24 hours.
  • A row with stale: true has no value: a figure below it was missing that night. Read the previous day.

​
The figures

There are four: member_count, waiting_count, net_growth_12m and young_people_count. What each one counts, and its edge cases, is on Data definitions. To count each young person once, read young_people_count: member_count counts a young person in two groups in each. value is the total for that group or node and everything below it that shares with it. ownValue is the part counted on its own records: a district’s own units, for example. Counts are exact, section counts included. That is why no figure about health, special needs or anything else sensitive is offered: in a small group, an exact count of one could identify a child.

​
One row per node, figure, section and night

GET /nodes/metrics is in long format. Each row is one figure for one group or node, one section and one night:

​
Sections

section is one of: The sections of a figure sum to its all row exactly. Data definitions says which figures have section rows. Nights built before version 1.8.0 was deployed have all rows only. The section query parameter picks the rows:
  • Left out, or section=all: the totals only. One row per group or node, figure and night.
  • A section, for example section=cubs: that section’s rows only.
  • section=any: every row, the totals and each section. Do not add a section row to its total: each young person would count twice.
Adding rows up. A row’s value already includes every group and node below it that shares with it. So do not add value across a district and its groups: each young person would count twice. For your own total, read your own node’s value. To total a set of rows yourself, add their ownValue. A stale section row makes only that row stale. The other sections, and the total, can still have a value.

​
Try it

The sandbox key is a group key, so it cannot read these endpoints. Use your own district or area key on the live API. Put it in the SCOUTWORKS_API_KEY environment variable first, so it stays out of your shell history:
The same figure for each section:
District totals in Google Sheets puts every group’s numbers in a sheet that refreshes each morning.