Skip to content

About

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

Repository files navigation

AppBlockList .NET client

NuGet License: MIT

The AppBlockList NuGet package looks up mobile apps by identifier and tells you what they are: name, developer, App Store genre, age rating and a ranked set of filtering categories. It is written for the people who run Microsoft Intune, Jamf or Google Admin and need to turn "no social media on student devices" into a concrete list of bundle IDs and package names.

dotnet add package AppBlockList
  • Targets .NET 6, works on .NET 7, 8 and later
  • Uses only System.Net.Http and System.Text.Json from the framework
  • Async all the way, CancellationToken everywhere
  • Plays well with IHttpClientFactory and dependency injection
  • Typed exceptions for every documented error, and 404 as a normal result

Data comes from AppBlockList, operated by Alpha Quantum.


Quick start

Set the key as an environment variable (or pass it to the constructor):

$env:APPBLOCKLIST_API_KEY = "your-key"
using AppBlockList;

using var client = new AppBlockListClient();

var app = await client.LookupAsync("com.zhiliaoapp.musically");

Console.WriteLine(app.Name);                                  // TikTok - Videos, Shop & LIVE
Console.WriteLine(app.AgeRating);                             // 12+
Console.WriteLine(string.Join(", ", app.FilteringCategories)); // Social Networking, Streaming Media
Console.WriteLine(app.AndroidPackage);                        // com.zhiliaoapp.musically
Console.WriteLine(app.InCategory("Social Networking"));       // True

LookupAsync takes any of the identifiers you find in an MDM console:

  • an iOS bundle ID such as com.zhiliaoapp.musically
  • an App Store ID, 835599320 or id835599320
  • an Android package name such as com.openai.chatgpt

The same record answers for both stores when the app exists on both, so one call gives you the identifiers for iPhone, iPad and Android devices.


The Intune console job

This is the scenario the package was built around. An Intune administrator exports the list of apps found on managed devices, and wants two plain lists out of it: iOS bundle IDs and Android package names that break the organization's policy. The full program is in examples/IntuneBlockJob.

Run it

dotnet run --project examples/IntuneBlockJob -- `
    --in .\discovered-apps.csv `
    --column "Bundle ID" `
    --block "Social Networking,Streaming Media" `
    --max-age 12 `
    --out .\out

The job prints how many inventory rows it read, how many apps it checked and how many iOS and Android IDs it wrote to the block files.

Without --column, the job picks the first header that mentions a bundle ID, package or app ID. Duplicate rows (the same app on many devices) are looked up once.

What it writes

File Contents
out/ios-bundle-ids.txt One bundle ID per line, sorted
out/android-packages.txt One package name per line, sorted
out/report.csv Every app with name, developer, age rating, categories, verdict and reason

The report is the part people end up valuing most. When a principal or a department head asks why an app disappeared, the reason column says "category Social Networking" or "age rating 17+".

How it decides

private static (string Verdict, string Reason) Decide(LookupOutcome o, string[] blocked, int? maxAge)
{
    if (!o.IsOk) return ("error", o.Error!.Message);
    var app = o.App!;
    if (!app.Found) return ("unknown", app.Message ?? "");
    if (app.InCategory(blocked)) return ("block", "category " + app.PrimaryCategory);
    if (maxAge is int max && app.MinimumAge is int min && min > max)
        return ("block", "age rating " + app.AgeRating);
    return ("allow", "");
}

The lookup loop

using var client = new AppBlockListClient();

try
{
    await foreach (var outcome in client.LookupManyAsync(ids, TimeSpan.FromMilliseconds(100), cts.Token))
    {
        var (verdict, reason) = Decide(outcome, blocked, maxAge);
        if (verdict == "block" && outcome.App is { } app)
        {
            if (!string.IsNullOrEmpty(app.BundleId)) ios.Add(app.BundleId);
            if (app.IsOnGooglePlay) android.Add(app.AndroidPackage);
        }
        // append to report.csv ...
    }
}
catch (QuotaExceededException e)
{
    Console.Error.WriteLine($"Monthly lookups used up ({e.MonthlyLookups}); writing partial output.");
}

LookupManyAsync streams results as an IAsyncEnumerable<LookupOutcome>. It sends requests one after another, as the service asks, skips blanks and duplicates, records per-app errors in the outcome, and throws on a bad key or an exhausted quota so the job stops cleanly.

Getting the lists into Intune

Where the lists go depends on platform and enrollment type. For supervised iOS and iPadOS devices, restricted apps live in a device restrictions profile; on Android Enterprise, apps are blocked through app assignments and policies. The step-by-step guide to blocking apps with Microsoft Intune covers where each list goes. Apple's side of the restriction keys is documented in the Apple device management reference.

Scheduling

The job is a plain console app, so any scheduler works:

Where How
A Windows management server Task Scheduler, weekly, running dotnet IntuneBlockJob.dll with arguments
A Linux runner cron with APPBLOCKLIST_API_KEY in the environment
A CI system A scheduled pipeline that publishes out/ as an artifact for review

Run it weekly or after each new export. App categories change slowly, so you can also keep last week's report.csv and only look up IDs that are new.


ASP.NET Core: an app request endpoint

Help desks often get "can you allow this app?" tickets. A minimal API can answer the clear cases on the spot. Register the client through IHttpClientFactory so connections are pooled and handlers rotate:

using AppBlockList;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient("appblocklist", http => http.Timeout = TimeSpan.FromSeconds(10))
    .AddTypedClient<AppBlockListClient>((http, sp) =>
        new AppBlockListClient(sp.GetRequiredService<IConfiguration>()["AppBlockList:ApiKey"], http));

builder.Services.AddMemoryCache();

var app = builder.Build();

string[] denied = { "Social Networking", "Streaming Media" };

app.MapGet("/apps/check", async (string id, AppBlockListClient client, IMemoryCache cache, CancellationToken ct) =>
{
    try
    {
        var info = await cache.GetOrCreateAsync(id, entry =>
        {
            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromDays(1);
            return client.LookupAsync(id, ct);
        });

        if (info is null || !info.Found)
            return Results.Ok(new { id, verdict = "review", reason = info?.Message });

        return info.InCategory(denied)
            ? Results.Ok(new { id, verdict = "deny", reason = "category " + info.PrimaryCategory, info.Name })
            : Results.Ok(new { id, verdict = "approve", info.Name, info.AgeRating, info.FilteringCategories });
    }
    catch (InvalidAppIdException e)
    {
        return Results.BadRequest(new { error = e.Message });
    }
    catch (AppBlockListException e)
    {
        return Results.Ok(new { id, verdict = "review", reason = "lookup failed: " + e.Message });
    }
});

app.Run();
// appsettings.json
{ "AppBlockList": { "ApiKey": "set this from a secret store, not in the file" } }

The client never disposes an HttpClient that you pass in, so it is safe with the factory. The cache keeps repeated requests for popular apps from spending lookups.


Unit testing without the network

ParseResponse(int status, string body) is the same function LookupAsync runs after the HTTP call. Feed it recorded JSON and your policy code gets real AppInfo objects:

[Fact]
public void UnknownAppsGoToReview()
{
    var app = AppBlockListClient.ParseResponse(404, @"{""found"": false, ""error"": ""App not found.""}");
    Assert.Equal("review", MyPolicy.Evaluate(app));
}

To test the HTTP path too, pass an HttpClient built on a fake HttpMessageHandler, as the package's own tests in tests/AppBlockList.Tests do:

using var http = new HttpClient(new FakeHandler());
using var client = new AppBlockListClient("test-key", http, "https://example.invalid/api/v1")
{
    RetryDelay = TimeSpan.FromMilliseconds(1),
};

Run the suite with dotnet test tests/AppBlockList.Tests. It makes no network calls.


Reference

AppBlockListClient

Member Description
AppBlockListClient(string? apiKey = null, HttpClient? httpClient = null, string? baseUrl = null) Null key reads APPBLOCKLIST_API_KEY
Task<AppInfo> LookupAsync(string id, CancellationToken ct = default) One lookup
IAsyncEnumerable<LookupOutcome> LookupManyAsync(IEnumerable<string> ids, TimeSpan pause = default, CancellationToken ct = default) Sequential lookups, duplicates skipped
static AppInfo ParseResponse(int status, string? body) Map a raw answer to a result or exception
static string ValidateId(string? id) Local check: trimmed, non-empty, at most 200 characters, no spaces
int MaxRetries { get; set; } Retries for 5xx and network errors, default 2
TimeSpan RetryDelay { get; set; } First retry delay, doubled each time, default 1 second
void Dispose() Disposes the internal HttpClient only if the client created it

Requests go to GET https://www.appblocklist.com/api/v1/app?id=<ID> with the key in the X-API-Key header and the User-Agent appblocklist-dotnet/1.0.0 (+https://www.appblocklist.com).

AppInfo

Property JSON Notes
Found found false on a 404
Name name
Developer developer
BundleId bundle_id iOS
AppStoreId app_store_id string, digits only
AndroidPackage android_package Google Play twin, or empty
AppStoreGenre app_store_genre One of 26 genres
AgeRating age_rating 4+, 9+, 12+, 17+
FilteringCategories filtering_categories Ranked, never null
DeveloperDomain developer_domain
IabCategory iab_category IAB content path
Message error Set on not-found answers

Computed helpers: PrimaryCategory, IsOnGooglePlay, MinimumAge (int?), InCategory(params string[]), InCategory(IEnumerable<string>) and BlockIds(). AppInfo serializes back to the API's JSON shape with System.Text.Json.

Errors

HTTP Thrown Meaning
400 InvalidAppIdException ID missing or not a bundle ID, App Store ID or package name
401 AppBlockListUnauthorizedException Key missing or invalid
403 QuotaExceededException Monthly lookups used up; MonthlyLookups carries the count
404 nothing AppInfo.Found == false, with Message and possibly AndroidPackage
500 AppBlockListServerException Temporary; retried automatically first
none AppBlockListException with StatusCode == 0 Network failure, timeout or missing key

All of them derive from AppBlockListException, which exposes StatusCode and IsTransient. A 404 has two possible messages: App not found. and Listed on Google Play, not yet in the categorized database. In the second case AndroidPackage is filled in.


Policy ideas by sector

The categories are the same 58 used for 120 million web domains, which makes it easy to keep app and web rules in step.

Schools. Many districts block social networking and streaming on student iPads, and restrict by age rating per grade band. US schools on E-rate also need web filtering under the Children's Internet Protection Act; pairing this package with a school web filter built for CIPA covers both sides. The FTC's COPPA rule is another reason to know what student devices run. Start from the guide to blocking apps on school iPads.

Businesses. Corporate devices usually focus on data leaving the organization: file sharing, personal AI assistants and VPN apps that bypass inspection. See the curated pages for AI apps on managed phones and VPN and proxy apps. The NIST mobile device security guidelines describe app vetting and deny lists as standard enterprise controls. For the browser side, the AI tools domain list covers web versions of the same services.

IT providers. Managed service providers running Intune tenants for many clients can run the console job per tenant and keep a separate output folder for each.


Why AppBlockList

  • Coverage. 1,874,397 iPhone and iPad apps, about 800,000 linked to their Android twin, and 3.9 million Google Play package names tracked.
  • One vocabulary. 58 filtering categories shared with web filtering, ranked per app so the most descriptive one comes first.
  • Reasons, not just lists. Category, age rating and developer travel with every answer.
  • Fair billing. Only 200 answers count as lookups; a 404 is free.

Plans

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, unlimited schools or clients, includes the API with 100,000 lookups a month
Mobile App Database $999 one-time (top 100,000 apps) or $1,999 one-time (top 500,000 apps)

If you would rather import a file than call an API, the monthly MDM app blocklist feed includes ready-made Intune import files, along with Jamf files, a .mobileconfig profile, plain ID lists and a full CSV. Prices are per organization, not per device. See plans and pricing.


FAQ

Does the package work with .NET Framework 4.8?

No. It targets .NET 6 and uses APIs such as IAsyncEnumerable and init-only properties. Any .NET 6 or later runtime on Windows, Linux or macOS works.

Should I create one client or many?

One. AppBlockListClient is thread-safe. In ASP.NET Core, register it as a typed client through IHttpClientFactory, as shown above. Keep concurrent calls per key to one, since the service asks for sequential requests.

Why is an unknown app not an exception?

Inventories always contain in-house builds, regional apps and brand new releases. Returning Found == false keeps loops and reports simple, and those lookups are not billed.

How do I find a bundle ID for an app my users mention by name?

Use the free App Store bundle ID search, or the package name lookup for Google Play.

Does the job work with Jamf or Google Admin instead of Intune?

Yes. The output files are plain lists. There are guides for Jamf Pro app restrictions, Google Admin and hand-built .mobileconfig profiles.

Can I license the whole catalogue?

Yes. The mobile app database download is a licensed file with 12 columns per app, including filtering and IAB categories.


Links

Related packages

Other official clients for the same API:

The npm and PyPI sources live at https://github.com/explainableaixai/appblocklist.

More from Alpha Quantum: the 120M-domain web filtering database, the URL categorization data feed and the website categorization API.

License

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

About

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