Home Original page

OP3 API Documentation

OP3 API (0.1.0)

Download OpenAPI specification:Download

Endpoint

Base url for all API calls: https://op3.dev/api/1

Authentication

Every call to the OP3 API requires a bearer token associated with a valid API Key.

Manage your API Keys and bearer tokens →

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

You can also use the sample bearer token preview07ce to preview API access on this instance.

hits

Lowest-level log records saved for every prefix redirect processed.

This is the raw material on which higher-level metrics like downloads can be derived.

Query hits

Perform a query of every request ("hit") logged using the redirect.

This can be used to verify that requests are stored properly in the system.

Results are returned in ascending order by time (plus uuid to break ties for multiple requests in the same millisecond) unless the desc param is specified.

You can filter by a time range and one additional optional dimension (url or hashedIpAddress, which only have data for the last 90 days).

For example, to view hits starting 24 hours ago in json format:

GET https://op3.dev/api/1/hits?start=-24h&format=json&token=preview07ce

Authorizations:

bearer_token_or_token_query_param

query Parameters
token

string

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

See the Authentication section above for how to obtain a token.

format

string

Default: "tsv"

Enum: "tsv" "json" "json-o" "json-a"

Output format

Defaults to tab-separated text (tsv), but also supports a object-based json format (aka json-o) or a more compact array-based json-a format.

limit

integer [ 0 .. 1000 ]

Default: 100

Maximum number of rows to return

start

string <ISO 8601 timestamp, date, or relative duration>

Example: start=2022-09-15T14:00:52.709Z

Filter by start time (inclusive) using a timestamp, date, or relative time (e.g. -24h)

You can specify either start or startAfter, not both

startAfter

string <ISO 8601 timestamp, date, or relative duration>

Example: startAfter=2022-09-15T14:00:52.709Z

Filter by start time (exclusive) using a timestamp, date, or relative time (e.g. -24h)

You can specify either start or startAfter, not both

end

string <ISO 8601 timestamp, date, or relative duration>

Example: end=2022-09-15T14:00:52.709Z

Filter by end time (exclusive) using a timestamp, date, or relative time (e.g. -24h)

url

string <url>

Example: url=https://op3.dev/e/example.com/path/to/episode.mp3

Filter by a specific episode url

Also supports trailing wildcards, i.e. "starts with" queries.

Example: url=https://op3.dev/e/example.com/path/to/*

hashedIpAddress

40-character hex

Example: hashedIpAddress=a3f1b92bc53ff9512253be45bc9c60047bddad55

Filter by a specific IP address secure hash

Raw IP addresses are never stored, only their secure hash, using rotating keys

You can specify hashedIpAddress=current to use the value corresponding to your current IP address

desc

boolean

If provided, sorts the results in time-descending order (most recent first)

Responses

Response samples

{

  • "rows": [

    • {

      • "time": "string",

      • "uuid": "string",

      • "hashedIpAddress": "string",

      • "method": "string",

      • "url": "string",

      • "userAgent": "string",

      • "referer": "string",

      • "range": "string",

      • "xpsId": "string",

      • "ulid": "string",

      • "edgeColo": "string",

      • "continent": "string",

      • "country": "string",

      • "timezone": "string",

      • "regionCode": "string",

      • "region": "string",

      • "metroCode": "string"

      }

    ],

  • "count": 0,

  • "queryTime": 0

}

downloads

Query show downloads

Authorizations:

bearer_token_or_token_query_param

path Parameters
showUuid

required

string <32-character hex>

Example: 3299ee267635404e9cd660088a755b34

Filter by the OP3 show uuid

query Parameters
token

string

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

See the Authentication section above for how to obtain a token.

format

string

Default: "tsv"

Enum: "tsv" "json" "json-o" "json-a"

Output format

Defaults to tab-separated text (tsv), but also supports a object-based json format (aka json-o) or a more compact array-based json-a format.

limit

integer [ 0 .. 20000 ]

Default: 100

Maximum number of rows to return

start

string <ISO 8601 timestamp, date, or relative duration>

Example: start=2023-02-23T21:01:45.797Z

Filter by start time (inclusive) using a timestamp, date, or relative time (e.g. -24h)

You can specify either start or startAfter, not both

startAfter

string <ISO 8601 timestamp, date, or relative duration>

Example: startAfter=2023-02-23T21:01:45.797Z

Filter by start time (exclusive) using a timestamp, date, or relative time (e.g. -24h)

You can specify either start or startAfter, not both

end

string <ISO 8601 timestamp, date, or relative duration>

Example: end=2023-02-23T21:01:45.797Z

Filter by end time (exclusive) using a timestamp, date, or relative time (e.g. -24h)

episodeId

string <64-character hex>

Example: episodeId=6e3c647698c647939f479e6e0b822ec7a2eaa30b4ca5488d8eeb8b08ac22cdf7

Filter by the OP3 episode id

bots

string

Default: "exclude"

Enum: "include" "exclude"

Whether or not to include downloads from known bots

skip

string

Value: "headers"

Whether or not to skip specific response metadata like TSV headers

continuationToken

string <Opaque token from a prior query response>

Continue a prior query if necessary

Responses

Response samples

{

  • "rows": [

    • {

      • "time": "string",

      • "url": "string",

      • "audienceId": "string",

      • "showUuid": "string",

      • "episodeId": "string",

      • "hashedIpAddress": "string",

      • "agentType": "string",

      • "agentName": "string",

      • "deviceType": "string",

      • "deviceName": "string",

      • "referrerType": "string",

      • "referrerName": "string",

      • "botType": "string",

      • "countryCode": "string",

      • "continentCode": "string",

      • "regionCode": "string",

      • "regionName": "string",

      • "timezone": "string",

      • "metroCode": "string"

      }

    ],

  • "count": 0,

  • "queryTime": 0,

  • "continuationToken": "string"

}

shows

View show information

Authorizations:

bearer_token_or_token_query_param

path Parameters
showUuidOrPodcastGuidOrFeedUrlBase64

required

string <32-character hex, guid, or urlsafe base-64>

Example: 3299ee267635404e9cd660088a755b34

query Parameters
token

string

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

See the Authentication section above for how to obtain a token.

episodes

enum

Default: "exclude"

Enum: "include" "exclude"

Whether or not to include episode information as well.

Responses

Response samples

Content type

application/json

{

  • "showUuid": "string",

  • "title": "string",

  • "podcastGuid": "string",

  • "statsPageUrl": "string",

  • "episodes": [

    • {

      • "id": "string",

      • "title": "string",

      • "pubdate": "string"

      }

    ]

}

queries

Query recent episodes with transcripts

Authorizations:

bearer_token_or_token_query_param

query Parameters
token

string

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

See the Authentication section above for how to obtain a token.

limit

integer [ 1 .. 100 ]

Default: 100

Maximum number of rows to return

Responses

Response samples

Content type

application/json

{

  • "asof": "string",

  • "episodes": [

    • {

      • "pubdate": "string",

      • "podcastGuid": "string",

      • "episodeItemGuid": "string",

      • "hasTranscripts": true,

      • "dailyDownloads": { }

      }

    ],

  • "queryTime": 0

}

Query the top apps for a given show

Authorizations:

bearer_token_or_token_query_param

query Parameters
token

string

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

See the Authentication section above for how to obtain a token.

showUuid

string <32-character hex>

Specify the show by OP3 show uuid.

Must provide either showUuid, podcastGuid or feedUrlBase64.

podcastGuid

string <32-character hex>

Specify the show by podcast:guid.

Must provide either showUuid, podcastGuid or feedUrlBase64.

feedUrlbase64

string <urlsafe base-64>

Specify the show by podcast feed url (as urlsafe base-64).

Must provide either showUuid, podcastGuid or feedUrlBase64.

Responses

Response samples

Content type

application/json

{

  • "showUuid": "string",

  • "appDownloads": { },

  • "queryTime": 0

}

Query the top apps across all OP3 shows

Authorizations:

bearer_token_or_token_query_param

query Parameters
token

string

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

See the Authentication section above for how to obtain a token.

deviceName

string

If specified, constrains the results to a single device (e.g. Apple iPhone).

Device names can be found in the opawg/user-agents-v2 device list.

Bear in mind not all user-agents contain enough info to derive the device, so this may be of limited utility.

userAgent

string

If specified, constrains the results to a single device (e.g. Apple iPhone) inferred from a given user agent using the opawg/user-agents-v2 device list.

Bear in mind not all user-agents contain enough info to derive the device, so this may be of limited utility.

Responses

Response samples

Content type

application/json

{

  • "appShares": { },

  • "deviceName": "string",

  • "minDate": "string",

  • "maxDate": "string",

  • "queryTime": 0

}

Query monthly/weekly download counts for one or more shows

Get number of monthly downloads (last 30 days) and average weekly downloads over the last four weeks.

Excludes bots. Updated daily.

You can pass in one or more OP3 show uuids, and the results in showDownloadCounts will be keyed by show, with the following data points for each show:

  • monthlyDownloads (number): total number of non-bot downloads for the show in the last 30 days
  • days (string): 30-character string, each character identifying whether (1) or not (0) the show had at least one-bot download in each of the last 30 days (ascending in time), useful in determining how to interpret monthlyDownloads for new shows
  • weeklyAvgDownloads (number): average number of non-bot downloads per week over the last four weeks (or at least the last few full weeks if new to OP3)
  • weeklyDownloads ([ number, number, number, number]): non-bot downloads per week over the last four weeks (ascending in time)
  • numWeeks (number): number of recent weeks with full data on OP3, denominator used in weeklyAvgDownloads. Usually 4, but can be less for new shows (e.g. 1 if we only have data for the last 10 days)

For example:

GET https://op3.dev/api/1/queries/show-download-counts?showUuid=a18389b8a52d4112a782b32f40f73df6&token=preview07ce

Authorizations:

bearer_token_or_token_query_param

query Parameters
token

string

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

See the Authentication section above for how to obtain a token.

showUuid

required

Array of strings <32-character hex> non-empty unique [ items <32-character hex > ]

Specify one or more shows by OP3 show uuid.

Responses

Response samples

Content type

application/json

{

  • "asof": "string",

  • "showDownloadCounts": { },

  • "queryTime": 0

}

Query download counts for a show's recent episodes

Authorizations:

bearer_token_or_token_query_param

query Parameters
token

string

Pass your bearer token either:

  • as an authorization header: Authorization: Bearer mytoken
  • or using this query param: ?token=mytoken

See the Authentication section above for how to obtain a token.

showUuid

required

string <32-character hex>

Specify the show by OP3 show uuid.

If you don't have this, you can look it up for a given podcast using View Show Information.

Responses

Response samples

Content type

application/json

{

  • "showUuid": "string",

  • "showTitle": "string",

  • "minDownloadHour": "string",

  • "maxDownloadHour": "string",

  • "episodes": [

    • {

      • "itemGuid": "string",

      • "title": "string",

      • "pubdate": "string",

      • "downloads1": 0,

      • "downloads3": 0,

      • "downloads7": 0,

      • "downloads30": 0,

      • "downloadsAll": 0

      }

    ],

  • "queryTime": 0

}