Know what an app is before a child opens it. appblocklist is the Dart client for the AppBlockList App Lookup API: send an iOS bundle ID, an App Store ID or an Android package name, get back the app's name, developer, age rating, genre and ranked filtering categories.
It runs everywhere Dart runs: Flutter on Android, iOS, macOS, Windows, Linux and the web, plus server-side Dart. The only dependency is package:http, and the SDK constraint is >=2.17.0 <4.0.0, so older Flutter projects can use it too.
final app = await AppBlockListClient(apiKey: key).lookup('com.toyopagroup.picaboo');
print('${app.name} ${app.ageRating} ${app.filteringCategories}');
// Snapchat 12+ [Social Networking]Flutter:
flutter pub add appblocklistPlain Dart (server, CLI):
dart pub add appblocklistOr by hand in pubspec.yaml:
dependencies:
appblocklist: ^1.0.0Import a single library:
import 'package:appblocklist/appblocklist.dart';This matters more for Flutter than for any other client. An API key compiled into an app that you install on a child's phone can be extracted from the binary. A key leak is not a safety problem for the child, but it is a billing problem for you.
The recommended layout for a parental-control or family app:
child device (Flutter app) your backend (Dart, or anything) AppBlockList
+---------------------------+ +-----------------------------+ +----------------+
| AppBlockListClient( | GET | checks the family token | GET | /api/v1/app |
| baseUrl: your proxy) | ------> | caches answers for a day | -----> | X-API-Key: ... |
| no API key on the device | | adds X-API-Key | | |
+---------------------------+ +-----------------------------+ +----------------+
The client supports this directly. When you pass baseUrl, the key becomes optional, and the client sends the same ?id= query to your server and parses the same JSON back. Recipe 2 below is a complete proxy in about 60 lines of dart:io.
For internal tools, desktop admin consoles and server jobs, pass the key directly or set APPBLOCKLIST_API_KEY.
import 'package:appblocklist/appblocklist.dart';
Future<void> main() async {
final client = AppBlockListClient(); // reads APPBLOCKLIST_API_KEY
final app = await client.lookup('com.zhiliaoapp.musically');
if (app.found) {
print(app.name); // TikTok - Videos, Shop & LIVE
print(app.developer); // TikTok Ltd.
print(app.ageRating); // 12+
print(app.minimumAge); // 12
print(app.primaryCategory); // the most descriptive category
print(app.androidPackage); // com.zhiliaoapp.musically
} else {
print('Unknown app: ${app.error}');
}
client.close();
}The key is resolved in this order:
apiKey:constructor argumentAPPBLOCKLIST_API_KEYfrom the process environment (native platforms only)--dart-define=APPBLOCKLIST_API_KEY=...at compile time
If none is found and you did not pass baseUrl, the constructor throws AuthenticationException immediately.
| Member | Description |
|---|---|
AppBlockListClient({apiKey, baseUrl, httpClient, timeout, retries, retryDelay, userAgent}) |
Create a client. All arguments are optional. |
Future<AppResult> lookup(String id) |
One app. 404 resolves to found == false. |
Future<Map<String, AppResult?>> lookupAll(Iterable<String> ids, {Duration pause}) |
Sequential lookups, duplicates skipped, invalid IDs map to null. |
static AppResult parseResponse(int status, String body) |
Pure function: raw HTTP answer to result or exception. |
static String normalizeId(String id) |
Trim and enforce the 200 character limit. |
void close() |
Close the internal http.Client (only if the client created it). |
| Option | Default | Notes |
|---|---|---|
baseUrl |
https://www.appblocklist.com/api/v1/app |
point at your proxy in mobile apps |
httpClient |
new http.Client() |
pass your own for tests, IOClient with a custom HttpClient, or RetryClient |
timeout |
15 seconds | per request |
retries |
2 | extra attempts on 5xx, timeouts and network errors |
retryDelay |
1 second | doubled on each retry |
userAgent |
appblocklist-dart/1.0.0 (+https://www.appblocklist.com) |
not sent on the web, where browsers forbid it |
| Field or getter | Type | Example |
|---|---|---|
found |
bool |
true |
name |
String |
Snapchat |
developer |
String |
developer name from the store |
bundleId |
String |
com.toyopagroup.picaboo |
appStoreId |
String |
digits, as a string |
androidPackage |
String |
com.snapchat.android, or empty |
appStoreGenre |
String |
one of 26 App Store genres |
ageRating |
String |
4+, 9+, 12+, 17+ |
filteringCategories |
List<String> |
ranked, unmodifiable |
developerDomain |
String |
e.g. tiktok.com |
iabCategory |
String |
IAB taxonomy path |
error |
String? |
message when found is false |
primaryCategory |
String? |
first category |
minimumAge |
int? |
12 for 12+ |
isPendingAndroid |
bool |
on Google Play, not yet categorized |
hasCategory(c), matchingCategories(list), isBlockedBy(list) |
policy helpers, case-insensitive | |
toJson(), AppResult.fromJson(map) |
for caching in shared_preferences, Hive or SQLite |
Filtering categories come from a fixed set of 58, the same set used for 120 million web domains. A family profile that says "no Gambling" can therefore apply to websites in the browser and to apps on the device with one setting.
| HTTP | Meaning | Thrown |
|---|---|---|
| 200 | found | nothing |
| 404 | not in the database, or on Google Play but not yet categorized | nothing, found == false |
| 400 | id missing or not a valid identifier |
InvalidIdException |
| 401 | missing or invalid key | AuthenticationException |
| 403 | monthly lookups used up | QuotaExceededException with monthlyLookups |
| 500 | temporary error | ServerException, after retries |
| none | timeout, DNS, TLS, not JSON | TransportException, after retries |
All of them extend AppBlockListException, which carries message, statusCode and the decoded body.
try {
final app = await client.lookup(id);
// ...
} on InvalidIdException {
showSnack('That does not look like an app ID.');
} on QuotaExceededException catch (e) {
log('Lookup quota reached: ${e.monthlyLookups}');
return Verdict.askParent;
} on AppBlockListException catch (e) {
log('Lookup failed: $e');
return Verdict.askParent; // fail towards the parent, not towards "allowed"
}A family app usually has a profile per child with an age and a set of blocked categories. When the child requests an app, or when your platform plugin reports a newly installed package, the app asks for a verdict.
How you obtain the installed package list depends on the platform and on the permissions your app holds; on Android this is typically a platform channel or a plugin. The check itself is plain Dart:
import 'package:appblocklist/appblocklist.dart';
enum Verdict { allowed, blocked, askParent }
class ChildProfile {
final String name;
final int age;
final Set<String> blockedCategories;
const ChildProfile(this.name, this.age, this.blockedCategories);
}
class AppGate {
AppGate(this._client);
final AppBlockListClient _client;
final Map<String, AppResult> _cache = {};
Future<Verdict> check(String id, ChildProfile child) async {
final AppResult app;
try {
app = _cache[id] ??= await _client.lookup(id);
} on AppBlockListException {
return Verdict.askParent;
}
if (!app.found) return Verdict.askParent;
if (app.isBlockedBy(child.blockedCategories)) return Verdict.blocked;
final minAge = app.minimumAge;
if (minAge != null && minAge > child.age) return Verdict.blocked;
return Verdict.allowed;
}
}And a screen that uses it:
import 'package:flutter/material.dart';
final gate = AppGate(AppBlockListClient(
baseUrl: 'https://family.example.org/api/app-check', // your proxy, no key on device
));
const mia = ChildProfile('Mia', 10, {
'Social Networking', 'Dating', 'Gambling', 'Adult', 'VPN / Proxy / Anonymizers',
});
class AppRequestTile extends StatelessWidget {
const AppRequestTile({super.key, required this.packageName});
final String packageName;
@override
Widget build(BuildContext context) {
return FutureBuilder<Verdict>(
future: gate.check(packageName, mia),
builder: (context, snap) {
if (!snap.hasData) {
return ListTile(title: Text(packageName), trailing: const CircularProgressIndicator());
}
final v = snap.data!;
return ListTile(
title: Text(packageName),
subtitle: Text(verdictLabel(v)),
leading: Icon(v == Verdict.allowed ? Icons.check_circle : Icons.block,
color: v == Verdict.allowed ? Colors.green : Colors.red),
);
},
);
}
}
String verdictLabel(Verdict v) {
switch (v) {
case Verdict.allowed:
return 'Allowed for Mia';
case Verdict.blocked:
return 'Blocked by Mia\'s profile';
case Verdict.askParent:
return 'Waiting for a parent to decide';
}
}A few points that make this production-worthy:
- Fail towards the parent. Network errors and unknown apps return
askParent, neverallowed. - Age and category together. A
17+app with harmless categories is still blocked for a ten-year-old byminimumAge. - Cache. The in-memory map avoids repeated lookups in one session; persist
toJson()for longer.
Apps aimed at children under 13 in the US also fall under the FTC's COPPA Rule. Sending only an app identifier to your proxy, and no child identity, keeps the lookup itself free of personal data.
This server sits between your Flutter app and AppBlockList. It validates a family token, caches answers for a day, and forwards the response with the same status code and JSON shape, so the client on the device parses it unchanged.
// bin/proxy.dart (run with APPBLOCKLIST_API_KEY and FAMILY_TOKENS set)
import 'dart:convert';
import 'dart:io';
import 'package:appblocklist/appblocklist.dart';
final _cache = <String, MapEntry<DateTime, Map<String, dynamic>>>{};
Future<void> main() async {
final abl = AppBlockListClient(retries: 1);
final tokens = (Platform.environment['FAMILY_TOKENS'] ?? '').split(',').toSet();
final server = await HttpServer.bind(InternetAddress.anyIPv4, 8080);
print('Listening on :8080');
// `await for` handles one request at a time, which also keeps upstream
// lookups sequential, as the API asks.
await for (final req in server) {
final res = req.response..headers.contentType = ContentType.json;
if (req.uri.path != '/api/app-check') {
res.statusCode = 404;
await res.close();
continue;
}
if (!tokens.contains(req.headers.value('x-family-token'))) {
res.statusCode = 401;
res.write(jsonEncode({'error': 'Unknown family token.'}));
await res.close();
continue;
}
final id = (req.uri.queryParameters['id'] ?? '').trim();
final hit = _cache[id];
if (hit != null && DateTime.now().difference(hit.key) < const Duration(days: 1)) {
res.statusCode = hit.value['found'] == true ? 200 : 404;
res.write(jsonEncode(hit.value));
await res.close();
continue;
}
try {
final app = await abl.lookup(id);
final body = app.toJson();
_cache[id] = MapEntry(DateTime.now(), body);
res.statusCode = app.found ? 200 : 404;
res.write(jsonEncode(body));
} on InvalidIdException catch (e) {
res.statusCode = 400;
res.write(jsonEncode({'error': e.message}));
} on AppBlockListException catch (e) {
stderr.writeln('upstream: $e');
res.statusCode = 500; // the device client will retry, then ask the parent
res.write(jsonEncode({'error': 'Temporary error.'}));
}
await res.close();
}
}On the device, add the token header by passing a small wrapping http.BaseClient as httpClient:
import 'package:http/http.dart' as http;
class FamilyTokenClient extends http.BaseClient {
FamilyTokenClient(this._token, [http.Client? inner]) : _inner = inner ?? http.Client();
final String _token;
final http.Client _inner;
@override
Future<http.StreamedResponse> send(http.BaseRequest request) {
request.headers['x-family-token'] = _token;
return _inner.send(request);
}
}
final client = AppBlockListClient(
baseUrl: 'https://family.example.org/api/app-check',
httpClient: FamilyTokenClient(savedToken),
);Note that the proxy deliberately maps upstream 401 and 403 to a generic 500. The device does not need to know about your billing state, and the parent sees "waiting for a decision" instead of an error.
Server-side Dart is handy for a scheduled job that reviews what is installed across a fleet. Feed it a text file of identifiers exported from your device manager, one per line:
// bin/report.dart ids.txt
import 'dart:io';
import 'package:appblocklist/appblocklist.dart';
const policy = {
'Gaming', 'Gambling', 'Dating', 'Adult', 'AI / LLM Tools', 'VPN / Proxy / Anonymizers',
};
Future<void> main(List<String> args) async {
final ids = await File(args.first).readAsLines();
final client = AppBlockListClient(retries: 3);
final byCategory = <String, List<String>>{};
final review = <String>[];
try {
final results = await client.lookupAll(ids, pause: const Duration(milliseconds: 100));
for (final entry in results.entries) {
final app = entry.value;
if (app == null || !app.found) {
review.add(entry.key);
continue;
}
for (final c in app.matchingCategories(policy)) {
byCategory.putIfAbsent(c, () => []).add('${app.name} (${entry.key})');
}
}
} on QuotaExceededException {
stderr.writeln('Monthly lookups used. Partial report follows.');
} finally {
client.close();
}
byCategory.forEach((cat, apps) {
print('\n## $cat (${apps.length})');
apps.forEach(print);
});
print('\n## Needs review (${review.length})');
review.forEach(print);
}0 4 * * * cd /opt/fleet && dart run bin/report.dart exports/ids.txt > reports/$(date +\%F).md
The resulting lists plug straight into managed configurations. For iOS, blocked bundle IDs go into the Restrictions payload described in Apple's Device Management documentation; for managed Android devices, the controls are covered in Android Enterprise for developers. AppBlockList also has a step-by-step guide for Google Admin console app blocking, useful for Chromebook and Android fleets.
| Platform | Key from env | User-Agent sent | Notes |
|---|---|---|---|
| Android, iOS | via --dart-define |
yes | use a proxy for apps on children's devices |
| macOS, Windows, Linux | env or define | yes | fine for admin tools |
| Web | --dart-define only |
no (browser rule) | call your own backend; the custom X-API-Key header triggers a CORS preflight |
| Dart VM (server, CLI) | env or define | yes | the natural home for sync jobs |
Responses are plain JSON as defined in RFC 8259, so the cached toJson() maps can be shared with services in other languages.
- Category, not just name. Copycat apps and new releases are judged by what they are. A brand-new VPN lands in
VPN / Proxy / Anonymizerswithout a code update. - iOS and Android in one record. About 800,000 iOS apps carry their Google Play twin, and 3.9 million Google Play package names are tracked.
- Ranked categories. The first entry is the most descriptive, which keeps UI labels honest: "Snapchat: Social Networking".
- Same policy for web and apps. 58 categories shared with the website database, so the browser filter and the app gate agree.
- Explainable.
matchingCategoriesgives a parent the reason in their own words.
| 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 |
| Districts and IT Providers | $249/month or $2,490/year, includes the API with 100,000 lookups a month |
| Mobile App Database | top 100,000 apps $999, top 500,000 apps $1,999, one-time |
Lookups are counted only for 200 answers. Details on the plans page.
You can, by passing apiKey, but anyone with the APK or IPA can recover the key. For apps on children's devices, use the proxy pattern from Recipe 2 and pass baseUrl instead.
Yes. It reads no environment there and does not try to set User-Agent. Route requests through your own backend, which also avoids exposing the key.
The service asks for one ID per request and requests sent one after another. lookupAll awaits each lookup before starting the next, and the proxy in Recipe 2 handles one request at a time.
Treat it as "ask a parent" or "needs review". In-house, regional and very new apps are often missing. When isPendingAndroid is true, the package exists on Google Play but is not yet categorized.
Pass MockClient from package:http/testing.dart as httpClient, exactly as the package's own tests do:
final client = AppBlockListClient(
apiKey: 'test',
httpClient: MockClient((_) async => http.Response('{"found": false, "error": "App not found."}', 404)),
);The bundle ID finder and the Android package lookup cover single apps. For curated starting points, see the list of AI apps and the list of VPN and proxy apps.
Yes. The monthly blocklist feed for MDM covers all 58 categories in six formats, including a .mobileconfig profile. For offline analysis there is the licensed App Store app database with 1,874,397 iPhone and iPad apps.
- AppBlockList and the App Lookup API docs
- School guidance: which apps to block on school iPads
- Support: contact, info@alpha-quantum.com
- Source: github.com/explainableaixai/appblocklist-dart
Other Alpha Quantum services that pair well with an app gate:
- block AI chatbots and AI sites
- web filtering built for CIPA compliance
- web filtering data for 120 million domains
- offline URL categorization database
- website category lookup API
| Ecosystem | Where |
|---|---|
| npm | appblocklist |
| PyPI | appblocklist |
| PHP (Composer) | appblocklist-php |
| Ruby | appblocklist-ruby |
| Elixir | appblocklist-elixir |
| Go | appblocklist-go |
| Java | appblocklist-java |
| Rust | appblocklist-rust |
| .NET | appblocklist-dotnet |
| Product repo | explainableaixai/appblocklist and GitLab |
MIT License, Copyright (c) 2026 Alpha Quantum. See LICENSE.