Skip to content

About

Go client for the AppBlockList App Lookup API: filtering categories, age rating and iOS/Android IDs for 1.87M apps

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

appblocklist-go

Go Reference License: MIT

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.


Five-minute tour

Get an API key from the App Lookup API plans and export it:

export APPBLOCKLIST_API_KEY=your-key

Then:

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.


What comes back

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 known

The 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.


Client options

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.

Functions and methods

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

Errors

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."}

Recipe 1: a nightly cron job over an MDM inventory CSV

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-cron
15 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.csv

A few habits make this job cheap to run:

  • De-duplicate first. A fleet of 3,000 iPads usually carries a few hundred distinct apps. LookupMany drops 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 AndroidPackage is 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.


Recipe 2: an app request handler for an approval portal

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.


Recipe 3: a CI check for an allowlist file

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.


Testing your own code

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 == nil

If 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.


Using the API politely

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.


Why look apps up instead of keeping a list by hand

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.

When a file beats an API

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.


FAQ

Which ID should I send if the MDM gives me several?

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.

Does a 404 cost a lookup?

No. Only 200 answers are counted. The client returns a 404 as an *App with Found == false and the API's message in Message.

Can I call Lookup from many goroutines at once?

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.

How do I find an ID without writing code?

Use the free bundle ID lookup tool for iOS apps or the Android package name finder.

Is there a ready list of AI apps or VPN apps?

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.

What does the response look like as raw JSON?

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.


Links

Related packages

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.

License

MIT. Copyright (c) 2026 Alpha Quantum. See LICENSE.

About

Go client for the AppBlockList App Lookup API: filtering categories, age rating and iOS/Android IDs for 1.87M apps

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages