Docs
View as Markdown

Metric differences between platforms

Platforms do not measure the same things. Onekey maps every platform onto one unified schema, and where a platform has no equivalent of a field it says so instead of inventing one.

The rule#

  • A fixed-schema field means one thing everywhere. author.followers is a follower count on every platform that emits it; engagement.likes is a like count. If a platform's number is something else (a "reach", a "score", a "karma"), it does not go in the shared field.
  • No substitution. If a platform does not expose a value, the field is null when the endpoint maps it and absent when it does not. A different number is never put in its place. See Honest nulls.
  • Near-equivalents live under ext. A platform-specific metric that is close to, but not the same as, a shared one is returned under ext.<name> with its own name, documented on the endpoint page. You choose whether it is good enough for your purpose.

How to see what a given endpoint returns#

  1. Open the endpoint page and read Field mapping: it lists every field the endpoint emits.
  2. Look at the Recorded response. A mapped field with no value for that record is null.
  3. Call GET /v1/platforms for the same information in JSON.

Computed values#

The computed block adds engagement_rate, estimated_reach and language on many endpoints. They are arithmetic or detection over fields already in the answer, with the rule published and a warning when an input is missing, so the value is null rather than a guess when the inputs are not there.

Practical advice#

  • For cross-platform code read only fixed-schema fields, and treat null as unknown.
  • Do not compare a raw count across platforms without checking what the platform counts (a view on one platform may be a play or an impression on another). The platform's own definition is the one that holds.
  • If you need a metric a platform does not expose, it is not available from public data. Say so in your product rather than estimating it.

Next#