How "Unique audience" is calculated.

[sebsto]

Hello,

The "Unique audience" reported on the web page for my show is 2946 for March 2025
See https://op3.dev/show/d8347e02-cf46-566b-924b-468b4d848aee

I understand this is the count of unique downloads by an IP hash for the period.

But when I download the raw data and count by myself, I count 2215.
Can you help to understand why the difference ?

Here are the command I use to download and count.

MY_API_KEY=aaaa
curl -s "https://op3.dev/api/1/downloads/show/82002a7f8d7e4ac29715b95b110c9339?token=${MY_API_KEY}&limit=20000&start=2025-03-01T00%3A00%3A00.000Z&end=2025-03-31T23%3A59%3A59.999Z&format=json-o" | jq '.rows | map(.hashedIpAddress) | unique | length' 

[jamescridland]

Unique audience is normally calculated using (User Agent + IP) not just IP.

So, two users from one IP address, one on iPhone, one on Android, will correctly count as 2.

https://op3.dev/download-calculation doesn't make this clear, incidentally; might be a good documentation tweak.

[sebsto]

Thank you @jamescridland I missed that part.
But even when I sum the combination of ipHash, agentName, deviceType, and devicename, I still receive 2239 instead of the 2946 reported on the web page.

unique_listeners.add((ip_hash, agent, deviceType, deviceName or ""))    

or with jq

jq '[.rows[] | {ip: .hashedIpAddress, agent: .agentName, type: .agentType, device: .deviceName, deviceType: .deviceType }] | unique | length' 202503.json

Where is the code responsible to compute the value on the web page, so that I can compare the two method of computing this value ?

[johnspurlock-skymethod]

Typically unique "listeners" (more accurately "downloaders") for computing audience are defined using the ip + user agent. OP3 uses hashedIpAddress + userAgent (+ referer if present for browser requests, as OP3 tries to treat podcast webapps as first-class citizens).

From Download Calculation

Duplicate requests in the same UTC day (24 hours) based on the secure IP address hash + User-Agent + Referer for the same normalized episode url are ignored.

The code that does this is here and I believe the audienceId is returned in that same API call you're using.

Note that since OP3 hashedIpAddress is computed based on a key that changes every month (for listener privacy purposes), you can't really sum or query audience numbers across UTC month boundaries. It looks like you're already aware of that, staying within the month of March should be fine.

[sebsto]

Thank you. I will check that.

• I am staying with the boundaries of a calendar month
• I also tried to count audienceId (jq '.rows | map(.audienceId) | unique | length') but it returns a lower number than what is on the web page (2265 vs 2946)

is my API call correct ? (I checked the limit already, the API returns 5602 rows, which is aligned with the total number of downloads on the web page)

curl -s "https://op3.dev/api/1/downloads/show/82002a7f8d7e4ac29715b95b110c9339?token=${MY_API_KEY}&limit=20000&start=2025-03-01T00%3A00%3A00.000Z&end=2025-03-31T23%3A59%3A59.999Z&format=json-o"