Go client for the AppBlockList App Lookup API. Give it an iOS bundle ID, an App Store ID or an Android package name and it returns the app's name, developer, store genre, age rating, its ranked filtering categories and an IAB category, as a typed *appblocklist.App.
go get github.com/explainableaixai/appblocklist-go
The module needs Go 1.19 or newer and imports nothing outside the standard library (net/http, encoding/json). It is a good fit for the small, boring programs that keep a device fleet in shape: nightly cron jobs, inventory reconcilers, approval portals and CI checks.
Get an API key from the App Lookup API plans and export it:
export APPBLOCKLIST_API_KEY=your-keyThen:
package main
import (
"context"
"fmt"
"log"
"github.com/explainableaixai/appblocklist-go"
)
func main() {
c := appblocklist.New("") // empty string: read APPBLOCKLIST_API_KEY
app, err := c.Lookup(context.Background(), "com.zhiliaoapp.musically")
if err != nil {
log.Fatal(err)
}
if !app.Found {
fmt.Println("not in the database:", app.Message)
return
}
fmt.Println(app.Name, "by", app.Developer)
fmt.Println("age rating:", app.AgeRating)
fmt.Println("categories:", app.FilteringCategories)
fmt.Println("block?", app.InCategory("Social Networking", "Streaming Media"))
}Output:
TikTok - Videos, Shop & LIVE by TikTok Ltd.
age rating: 12+
categories: [Social Networking Streaming Media]
block? true
The three accepted ID formats all reach the same record when the app exists on both stores:
| Input | Example |
|---|---|
| iOS bundle ID | com.zhiliaoapp.musically |
| App Store ID, digits | 835599320 |
| App Store ID, with prefix | id835599320 |
| Android package name | com.openai.chatgpt |
IDs can be up to 200 characters. The client trims whitespace and rejects empty or oversized IDs before it spends a request.
Lookup returns *App. The JSON tags match the API, so you can re-encode an App with encoding/json and get the same shape the endpoint sent.
| Field | JSON | Example | Notes |
|---|---|---|---|
Found |
found |
true |
false for a 404, which is a normal result |
Name |
name |
TikTok - Videos, Shop & LIVE |
Store listing name |
Developer |
developer |
TikTok Ltd. |
|
BundleID |
bundle_id |
com.zhiliaoapp.musically |
iOS identifier |
AppStoreID |
app_store_id |
835599320 |
Always a string in Go |
AndroidPackage |
android_package |
com.zhiliaoapp.musically |
Google Play twin, or empty |
AppStoreGenre |
app_store_genre |
Entertainment |
One of 26 App Store genres |
AgeRating |
age_rating |
12+ |
4+, 9+, 12+, 17+ |
FilteringCategories |
filtering_categories |
[Social Networking, Streaming Media] |
Ranked, most descriptive first, never nil |
DeveloperDomain |
developer_domain |
tiktok.com |
Useful for joining with web filter data |
IABCategory |
iab_category |
Technology & Computing > ... |
IAB content path |
Message |
error |
App not found. |
Only on not-found answers |
Three helper methods cover the questions people ask most often:
app.PrimaryCategory() // "Social Networking", the first ranked category
app.InCategory("streaming media") // true, case-insensitive match on any category
app.OnGooglePlay() // true when an Android package name is knownThe filtering categories come from a fixed list of 58. It is the same list that is applied to 120 million web domains, so a policy that blocks a category on the network can block the matching apps on the device. If you already filter the web with a domain categorization database, the app policy can reuse the same category names.
New returns a *Client with sensible defaults. Every field is exported, so you change behaviour by assignment rather than through option functions.
| Field | Default | Purpose |
|---|---|---|
APIKey |
argument to New, else $APPBLOCKLIST_API_KEY |
Sent as the X-API-Key header |
BaseURL |
https://www.appblocklist.com/api/v1 |
Point at an httptest.Server in tests |
HTTPClient |
&http.Client{Timeout: 30 * time.Second} |
Swap in a proxy-aware transport |
UserAgent |
appblocklist-go/1.0.0 (+https://www.appblocklist.com) |
|
MaxRetries |
2 |
Retries after a 500 or a network error |
RetryWait |
1s |
First backoff, doubled on each retry |
The key travels in a header rather than the query string, which keeps it out of proxy and web server logs. The API also accepts api_key= as a query parameter, but this client never uses it.
| Signature | What it does |
|---|---|
New(apiKey string) *Client |
Build a client, falling back to the environment variable |
(*Client) Lookup(ctx, id) (*App, error) |
One lookup, with retries for temporary errors |
(*Client) LookupMany(ctx, ids, pause) ([]Result, error) |
Sequential lookups with de-duplication |
ValidateID(id) (string, error) |
Local sanity check used by Lookup |
ParseResponse(status, body) (*App, error) |
Turn a raw HTTP answer into the same result Lookup gives |
(*App) PrimaryCategory() string |
First ranked category |
(*App) InCategory(names ...string) bool |
Any-of match on categories |
(*App) OnGooglePlay() bool |
Android twin known |
Every failure that came from the API is an *APIError with the HTTP status and the error text from the body. Each one also unwraps to a sentinel, so the idiomatic check is errors.Is:
| Status | Sentinel | Meaning | What to do |
|---|---|---|---|
| 400 | ErrInvalidID |
id missing or not a bundle ID, App Store ID or package name |
Fix the input, do not retry |
| 401 | ErrUnauthorized |
Missing or invalid key | Check configuration, stop the job |
| 403 | ErrQuotaExceeded |
Monthly lookups used up; MonthlyLookups holds the count |
Stop until the next period or upgrade |
| 404 | none | Not an error. App.Found is false |
Record and move on |
| 500 | ErrServer |
Temporary problem | Retried automatically, then returned |
Two more sentinels exist on the client side: ErrMissingAPIKey when there is no key at all, and ErrUnexpected for a status the API does not document or a body that is not JSON.
app, err := c.Lookup(ctx, id)
var apiErr *appblocklist.APIError
switch {
case errors.Is(err, appblocklist.ErrQuotaExceeded):
if errors.As(err, &apiErr) {
log.Printf("quota reached at %d lookups this month", apiErr.MonthlyLookups)
}
return err
case errors.Is(err, appblocklist.ErrInvalidID):
log.Printf("skipping malformed id %q", id)
case err != nil:
return err
case !app.Found && app.AndroidPackage != "":
log.Printf("%s is on Google Play but not categorized yet", app.AndroidPackage)
case !app.Found:
log.Printf("%s: %s", id, app.Message)
}The not-found case has two flavours, and both arrive as a normal *App:
{"found": false, "error": "App not found."}
{"found": false, "android_package": "com.example.app", "error": "Listed on Google Play, not yet in the categorized database."}Most MDM consoles can export installed apps as CSV. The job below reads that export, looks up each distinct ID once, and writes two files: a plain text list of IDs to block and a full report for the people who sign off on the policy. The complete program lives in examples/inventory-cron; the core is short:
ids, err := readColumn("/srv/mdm/inventory.csv", "Bundle ID")
if err != nil {
log.Fatal(err)
}
client := appblocklist.New("")
results, err := client.LookupMany(ctx, ids, 100*time.Millisecond)
if errors.Is(err, appblocklist.ErrQuotaExceeded) {
log.Printf("quota reached after %d apps, writing what we have", len(results))
} else if err != nil {
log.Fatal(err)
}
blocked := []string{"Social Networking", "Streaming Media"}
var out []string
for _, r := range results {
if r.Err != nil || !r.App.Found {
continue
}
if r.App.InCategory(blocked...) {
out = append(out, r.App.BundleID)
if r.App.OnGooglePlay() {
out = append(out, r.App.AndroidPackage)
}
}
}
os.WriteFile("/srv/mdm/blocked.txt", []byte(strings.Join(out, "\n")+"\n"), 0o644)Build it once and schedule it:
go build -o /usr/local/bin/inventory-cron ./examples/inventory-cron15 2 * * * APPBLOCKLIST_API_KEY=... /usr/local/bin/inventory-cron -in /srv/mdm/inventory.csv -column "Bundle ID" -block "Social Networking,Streaming Media" -out /srv/mdm/blocked.txt -report /srv/mdm/report.csvA few habits make this job cheap to run:
- De-duplicate first. A fleet of 3,000 iPads usually carries a few hundred distinct apps.
LookupManydrops exact duplicates for you. - Cache between runs. Store the report and only look up IDs that are new since last night. App categories change slowly.
- Write both IDs. When
AndroidPackageis set, add it next to the bundle ID, so a mixed fleet gets one list.
How the list reaches devices depends on the MDM. There are step-by-step pages for blocking apps in Microsoft Intune, for Jamf Pro restrictions, for Google Admin and for a raw .mobileconfig restrictions profile. Apple documents the payload keys in its device management reference.
Teachers and staff often ask IT to allow a specific app. A small internal web service can answer the easy cases instantly and send the rest to a human. This handler uses only net/http:
type decision struct {
ID string `json:"id"`
Name string `json:"name,omitempty"`
AgeRating string `json:"age_rating,omitempty"`
Categories []string `json:"categories,omitempty"`
Verdict string `json:"verdict"` // approve, deny, review
Reason string `json:"reason"`
}
var denyCategories = []string{"Social Networking"}
var maxAge = map[string]bool{"4+": true, "9+": true, "12+": true}
func requestHandler(c *appblocklist.Client) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
id := r.URL.Query().Get("id")
app, err := c.Lookup(r.Context(), id)
d := decision{ID: id}
switch {
case errors.Is(err, appblocklist.ErrInvalidID):
http.Error(w, "not a bundle ID, App Store ID or package name", http.StatusBadRequest)
return
case err != nil:
d.Verdict, d.Reason = "review", "lookup failed: "+err.Error()
case !app.Found:
d.Verdict, d.Reason = "review", app.Message
default:
d.Name, d.AgeRating, d.Categories = app.Name, app.AgeRating, app.FilteringCategories
switch {
case app.InCategory(denyCategories...):
d.Verdict, d.Reason = "deny", "category "+app.PrimaryCategory()
case !maxAge[app.AgeRating]:
d.Verdict, d.Reason = "deny", "age rating "+app.AgeRating
default:
d.Verdict, d.Reason = "approve", "within policy"
}
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(d)
}
}
func main() {
c := appblocklist.New("")
http.Handle("/check", requestHandler(c))
log.Fatal(http.ListenAndServe(":8080", nil))
}Because r.Context() is passed through, a client that disconnects cancels the lookup. A single shared *Client reuses connections; it is safe to call from many goroutines.
Under US law, schools that take E-rate funds must filter content that is harmful to minors under the Children's Internet Protection Act. The age rating and category fields give an approval portal a documented basis for each decision. For the web side of the same policy, see the CIPA filter for K-12 networks.
Some teams keep the list of approved apps in Git. A Go test can fail the build when somebody adds an app that the policy does not allow. Put this next to the file:
//go:build policy
package policy
import (
"bufio"
"context"
"os"
"strings"
"testing"
"github.com/explainableaixai/appblocklist-go"
)
func TestApprovedAppsStayWithinPolicy(t *testing.T) {
if os.Getenv("APPBLOCKLIST_API_KEY") == "" {
t.Skip("APPBLOCKLIST_API_KEY not set")
}
f, err := os.Open("approved-apps.txt")
if err != nil {
t.Fatal(err)
}
defer f.Close()
var ids []string
s := bufio.NewScanner(f)
for s.Scan() {
if line := strings.TrimSpace(s.Text()); line != "" && !strings.HasPrefix(line, "#") {
ids = append(ids, line)
}
}
res, err := appblocklist.New("").LookupMany(context.Background(), ids, 0)
if err != nil {
t.Fatal(err)
}
for _, r := range res {
switch {
case r.Err != nil:
t.Errorf("%s: %v", r.ID, r.Err)
case r.App.Found && r.App.InCategory("Social Networking", "Streaming Media"):
t.Errorf("%s (%s) is in %v", r.ID, r.App.Name, r.App.FilteringCategories)
case r.App.Found && r.App.AgeRating == "17+":
t.Errorf("%s (%s) is rated 17+", r.ID, r.App.Name)
}
}
}Run it in the pipeline with go test -tags policy ./policy/.... The build tag keeps it out of ordinary go test ./... runs, so local development does not spend lookups.
You never need the real API in unit tests. Point BaseURL at an httptest.Server that answers like the endpoint:
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusNotFound)
w.Write([]byte(`{"found": false, "error": "App not found."}`))
}))
defer srv.Close()
c := appblocklist.New("test")
c.BaseURL = srv.URL
app, err := c.Lookup(ctx, "com.example.unknown") // app.Found == false, err == nilIf you have recorded responses on disk, ParseResponse(status, body) gives the same result without any HTTP at all. The package's own tests in appblocklist_test.go follow this pattern and run offline.
The service asks for one ID per request and requests sent one after another, not in parallel bursts. LookupMany follows that rule and accepts an optional pause between calls. If you build your own loop, keep it sequential per key.
Only a 200 answer counts as a lookup. A 404 for an unknown app, a 400 for a malformed ID and a 401 for a bad key are free, so a sloppy input file costs you nothing but time.
A hand-maintained block list goes stale the week it is written. New social, streaming, AI and VPN apps appear every day, and each one has a bundle ID nobody on the IT team has seen before.
- Coverage. The database behind the API holds 1,874,397 iPhone and iPad apps, with about 800,000 linked to their Android twin and 3.9 million Google Play package names tracked.
- One vocabulary. The 58 filtering categories match what web filters use, so the same policy document covers sites and apps.
- Evidence. Category, age rating and developer give each block a reason you can show a principal, a parent or an auditor.
The NIST guidelines for managing mobile device security recommend application vetting and allow or deny lists as part of enterprise mobility. Background on the tooling itself is on Wikipedia's article on mobile device management.
If you only need the list, not lookups, the MDM blocklist feed ships it ready made every month in six formats: iOS bundle IDs, Android packages, a .mobileconfig profile, Intune and Jamf import files and a full CSV. For analytics or your own product, the Mobile App Database is a licensed file with 12 columns per app.
| Product | Price |
|---|---|
| App Lookup API | $99 per month for 100,000 lookups, higher volumes quoted |
| App Blocklists for MDM, school or business | $99/month or $990/year per organization |
| App Blocklists, districts and IT providers | $249/month or $2,490/year, includes the API with 100,000 lookups a month |
| Mobile App Database | $999 one-time (top 100,000 apps), $1,999 one-time (top 500,000 apps) |
Blocklist plans are priced per organization, not per device.
Send whichever you have. A bundle ID, an App Store ID with or without the id prefix, and an Android package name all work. If you have both an iOS and an Android ID for the same app, one lookup is enough, because the answer carries both.
No. Only 200 answers are counted. The client returns a 404 as an *App with Found == false and the API's message in Message.
The *Client is safe for concurrent use, but the service asks for sequential requests per key. Use LookupMany for lists, or put a single worker in front of the client if several parts of your program share it.
Use the free bundle ID lookup tool for iOS apps or the Android package name finder.
Yes, as pages you can read before you decide on a policy: AI apps to review and VPN and proxy apps. Schools often start from the guide on apps to block on school iPads. For AI tools reached through a browser rather than an app, the AI tools blocklist for networks covers the domains.
It is a single JSON object as defined in RFC 8259. app_store_id is a string; the client also accepts a number there in case you feed it data from other tools.
- Product: https://www.appblocklist.com
- API documentation: https://www.appblocklist.com/app-categorization-api.php
- Pricing: https://www.appblocklist.com/pricing.php
- Source: https://github.com/explainableaixai/appblocklist-go
- GitLab mirror of the product repo: https://gitlab.com/url-classifications/appblocklist
- Support: https://www.appblocklist.com/contact.php or info@alpha-quantum.com
Clients for the same API in other languages:
| Language | Package |
|---|---|
| JavaScript / Node.js | appblocklist on npm |
| Python | appblocklist on PyPI |
| Rust | appblocklist-rust |
| Java | appblocklist-java |
| .NET | appblocklist-dotnet |
The npm and PyPI packages live in the main repository at https://github.com/explainableaixai/appblocklist.
Sibling services from the same team: URL categorization database and website categorization API.
MIT. Copyright (c) 2026 Alpha Quantum. See LICENSE.