API
API reference
Query the same ranking the site shows. Create a key on your account. The reference below describes every endpoint that key can call.
Authentication
Send the key on every request:
Authorization: Bearer pb_live_...A key belongs to the account that created it. Only a hash is stored, so a lost key cannot be shown again: revoke it and create another. A browser session cookie also works, for a call made while you are signed in. The daily limit applies to keys, not to clicks in the browser.
Plans and limits
Pro includes apps, rankings and developer lookup. Business adds the changes feed. Limits are requests per key per UTC day.
| Plan | Requests / day | Endpoints |
|---|---|---|
| Pro | 1,000 | /apps, /developers, /rankings, /developer/{id} |
| Business | 20,000 | Everything in Pro, plus /changes |
CSV download stays on the ranking page. It is not an API call, and it has its own monthly row cap, shown on pricing.
Errors
| Status | When |
|---|---|
| 401 | No key, or a key that does not match. |
| 402 | The plan does not include this endpoint. Pro calling /changes is a 402. |
| 404 | No developer with that artist_id. |
| 422 | A parameter is the wrong shape. On /apps, page must be 1–10,000 and per_page 1–200. |
| 429 | That key has used its requests for the UTC day. |
An unknown filter value is dropped and the request still succeeds. A
type that is not one of Apple's categories is ignored, the
same way an empty field on the ranking form is ignored.
Apps
GET /api/v1/apps is the filtered ranking. Pro and Business.
The parameters are the same ones as the ranking page.
curl -H "Authorization: Bearer pb_live_..." \
"https://privacybench.online/api/v1/apps?category=finance&country=us&ratings=100000&stars=4"
The body is page, per_page, total
and results. Default page size is 50, and 200 is the most
one page returns. Sort defaults to score descending.
category is the genre slug from a ranking URL such as
/board/category/finance.
| Parameter | What it matches |
|---|---|
category | Genre slug. |
country | Storefront the app has charted in, such as us or de. |
q | Text in the app name or the developer name. |
grade | Score letter. Repeat the parameter, or send a comma-separated list. Letters: A, B, C, D, F. |
tracking | yes (Tracks users), no (No tracking), none (Declares no data collected). |
type | One of Apple's 16 data categories. Listed under allowed values. |
detail | A fine-grained type, such as Device ID. Listed under allowed values. |
purpose | Why the developer says the data is used. Listed under allowed values. |
group | tracking (To track you), linked (Linked to you), not_linked (Not linked to you). Applied only together with type, purpose or detail. |
price | free (Free), paid (Paid). |
ratings | Minimum number of ratings: 1000, 10000, 100000, 1000000. |
stars | Minimum average rating: 3, 4, 4.5. |
age | App Store age rating: 4+, 9+, 12+, 13+, 16+, 17+, 18+. |
updated | 30 (Last 30 days), 90 (Last 90 days), 365 (Last year), stale (Over a year ago). |
parent | Parent company, spelled as on the ranking filter. |
gap | 1 keeps apps that mention background location without a Location declaration. |
sort | score (Score), name (App), size (Size), tracking (Tracking types), linked (Linked types), types (Total types), seller (Developer), popularity (Rating count). Anything else sorts by score. |
order | desc (default) or asc. |
page | Starts at 1. |
per_page | 1–200. Default 50. |
Allowed values
Data categories for type:
Contact Info, Health & Fitness, Financial Info, Location, Sensitive Info, Contacts, User Content, Browsing History, Search History, Identifiers, Purchases, Usage Data, Diagnostics, Other Data, Surroundings, Body.
Fine types for detail:
Device ID, User ID, Email Address, Precise Location, Coarse Location.
Purposes:
Third-Party Advertising, Developer's Advertising or Marketing, Analytics, Product Personalization, App Functionality, Other Purposes.
Rankings
GET /api/v1/rankings is the shorter list: country,
genre (also accepted as genre_slug), q,
sort, order, page and per_page.
A per_page above 200 is read as 200. For purpose, rating,
tracking and the other filters, use /apps.
The result shape is the same.
Developers
GET /api/v1/developers is one row per developer. Pro and
Business. It takes the same parameters as /apps.
A developer is included when at least one scored app matches. On a filtered
request, apps and ranked count only those apps.
With no filters, apps is the whole portfolio and
ranked is how many of them have a score.
Sort is apps (default), score (average),
name or tracking. Each result has
artist_id, seller, apps,
ranked, avg_score, tracking_apps,
has_contact
and parent_company when one has been recorded.
The same list is on the developers page.
Two more parameters sit on the developer row.
min_apps is a minimum for the apps count on that
row: 2, 5, 10, 25, 50, 100.
With other filters on, that count is the matching apps; otherwise it is
the whole portfolio.
contact is yes or no.
yes means an email, phone or address is already stored from
the EU trader block. That block is collected by a separate pass, so
no also covers developers the pass has not reached yet.
One developer
GET /api/v1/developer/{artist_id} looks up one App Store
developer id. Pro and Business. Unknown ids are 404.
summary has apps, ranked,
avg_score and seller.
apps is a page of that developer's apps:
track_id, name, genre,
genre_slug, artwork_url, score,
tracking_types, linked_types,
total_types, file_size_bytes.
page and per_page work as on rankings, with the
same cap of 200.
Changes
GET /api/v1/changes is Business only. Each result is one app
whose declared categories differ between its two latest labeled snapshots:
track_id, name, genre,
genre_slug, captured_at, old_score,
new_score, and added / removed.
Each added or removed item is {"group", "data_type"}, where
data_type is a category such as Location, not a fine type.
Without track_id, the feed covers changes in the last 60 days.
limit defaults to 100 and stops at 500. With
track_id, the comparison is that app's two latest labeled
snapshots, however old the previous one is.
Fields on an app
Each object in /apps and /rankings results is one
ranked app. Times are ISO 8601.
| Field | Meaning |
|---|---|
track_id | Apple's numeric app id. |
name, seller, bundle_id | Listing name, developer, bundle id. |
genre, genre_slug | Category name, and the slug category filters on. |
score | Privacy score, 0–100. Higher means more declared collection. See the methodology. |
tracking_types, linked_types, not_linked_types, total_types | How many distinct data categories sit in each group. |
purpose_count | How many distinct purposes the label names. |
average_rating, rating_count | App Store rating. Rating count is a reach signal, not a download estimate. |
version, file_size_bytes, captured_at | The snapshot this row was scored from. |
countries | Storefront codes where the app has appeared on a chart. |
overall_rank, category_rank | Rank by score, overall and inside the genre. 1 is the highest score. |
artwork_url | App icon. |
Labels are what developers declare. They are not a measurement of what an app does. Questions about a response: [email protected].