Skip to content

About

Dart 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 for Dart and Flutter

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]

Getting it into your project

Flutter:

flutter pub add appblocklist

Plain Dart (server, CLI):

dart pub add appblocklist

Or by hand in pubspec.yaml:

dependencies:
  appblocklist: ^1.0.0

Import a single library:

import 'package:appblocklist/appblocklist.dart';

Before you write code: where should the key live?

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.


Quick start (server or CLI)

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:

  1. apiKey: constructor argument
  2. APPBLOCKLIST_API_KEY from the process environment (native platforms only)
  3. --dart-define=APPBLOCKLIST_API_KEY=... at compile time

If none is found and you did not pass baseUrl, the constructor throws AuthenticationException immediately.


Reference

AppBlockListClient

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

AppResult

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.


Exceptions

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

Recipe 1: a Flutter "can my child install this?" check

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, never allowed.
  • Age and category together. A 17+ app with harmless categories is still blocked for a ten-year-old by minimumAge.
  • 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.


Recipe 2: the backend proxy, in plain dart:io

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.


Recipe 3: a nightly policy report for school or family devices

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 notes

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.


Why AppBlockList for a family or school app

  • Category, not just name. Copycat apps and new releases are judged by what they are. A brand-new VPN lands in VPN / Proxy / Anonymizers without 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. matchingCategories gives a parent the reason in their own words.

Pricing in brief

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.


FAQ

Can I call the API straight from a Flutter app?

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.

Does the package work on Flutter web?

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.

Why are lookups sequential?

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.

What should I do with an app that is not found?

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.

How do I test widgets that use the client?

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)),
);

Where can I find bundle IDs and package names by hand?

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.

Is there a ready-made blocklist so I do not have to look apps up at all?

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.


Links

Other Alpha Quantum services that pair well with an app gate:


Related packages

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

License

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

About

Dart 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