Chicago Business Licenses Scraper

Search, filter, and export Chicago business licenses from the official City of Chicago open-data portal.

The Actor returns normalized business identity, license type and number, official status, activities, address, geography, issue dates, and expiration dates. Use it for repeatable compliance checks, local-market research, prospecting, and scheduled change monitoring.

What does Chicago Business Licenses Scraper do?

The Actor queries official Socrata datasets published by the City of Chicago.

It supports:

• full-text search across City records;
• partial legal-name and DBA-name matching;
• exact license number and official status-code lookup;
• license type, address, ZIP code, and ward filters;
• issued-date and expiration-date windows;
• all-records and current-active source datasets;
• deterministic pagination up to the requested limit;
• JSON, CSV, Excel, XML, and other Apify dataset exports.

Each output item is one official license row. No browser, login, or proxy is required.

Who is it for?

Compliance and risk teams

Verify a business's public license record, status, class, and expiration date before onboarding or during periodic reviews.

Sales and market-research teams

Build location-level lists by license type, ZIP code, ward, neighborhood, or business activity.

Data analysts

Load normalized Chicago license rows into spreadsheets, warehouses, dashboards, or entity-resolution pipelines.

Operations teams

Schedule a date-window query and compare datasets between runs to find newly issued, renewed, or changed records.

Why use the Actor instead of downloading manually?

The City portal is useful for one-off browsing, but recurring exports require repeatable query construction, pagination, normalization, and integration work.

This Actor provides:

1. a stable input contract;
2. server-side filtering at the official source;
3. normalized camelCase output;
4. bounded transient retries;
5. Apify scheduling and integrations;
6. a provenance URL and retrieval timestamp on every row.

The Actor does not enrich or infer license status. It preserves the City's published values.

Getting started

1. Open the Actor in Apify Console.
2. Enter a business name or another filter.
3. Choose All business license records or Current active licenses.
4. Set the maximum number of rows.
5. Click Start.
6. Open the License records dataset.
7. Export or connect the results to your workflow.

A useful first run is:

{
  "businessName": "Walgreens",
  "sourceDataset": "currentActive",
  "maxItems": 25
}

Input parameters

Field	Type	Default	Description
query	string	—	Full-text search across the official dataset.
businessName	string	—	Partial, case-insensitive legal or DBA name.
licenseNumber	string	—	Exact Chicago license number.
licenseStatus	string	—	Exact official status code, such as AAI.
licenseType	string	—	Partial match against the license description.
address	string	—	Partial licensed-address match.
zipCode	string	—	Exact ZIP code.
ward	string	—	Exact ward number.
issuedFrom	date	—	Earliest issue date, inclusive.
issuedTo	date	—	Latest issue date, inclusive.
expiresFrom	date	—	Earliest expiration date, inclusive.
expiresTo	date	—	Latest expiration date, inclusive.
sourceDataset	string	all	all or currentActive.
maxItems	integer	100	Maximum saved rows, from 1 to 50,000.

All supplied filters are combined. For example, a license type plus ZIP code returns only rows matching both.

Choose the right official dataset

Use currentActive when you need the City's current-active subset and want a smaller search surface.

Use all when you need historical applications, non-current rows, status filtering, or issue-date monitoring.

The source is updated by the City. A scheduled Actor run reflects what the official endpoint returns at run time.

Output fields

Important fields include:

Group	Fields
Identity	legalName, doingBusinessAsName, accountNumber, siteNumber
License	licenseId, licenseNumber, licenseCode, licenseType, licenseStatus
Activity	businessActivityIds, businessActivities, applicationType
Address	address, city, state, zipCode
Geography	ward, precinct, policeDistrict, communityAreaName, neighborhood
Dates	dateIssued, licenseStartDate, expirationDate, statusChangeDate
Provenance	sourceRecordId, sourceDataset, sourceUrl, retrievedAt

Fields can be null when the City does not publish a value for a row.

Output example

This abbreviated example reflects real current Actor behavior:

{
  "sourceRecordId": "1069844-20260516",
  "licenseNumber": "1069844",
  "legalName": "WALGREEN CO.",
  "doingBusinessAsName": "Walgreens #5926",
  "licenseType": "Retail Food Establishment",
  "licenseStatus": "AAI",
  "businessActivities": "Retail Sales of Perishable Foods",
  "address": "4385 S ARCHER AVE 1ST",
  "zipCode": "60632",
  "ward": "12",
  "dateIssued": "2026-05-13T00:00:00.000",
  "expirationDate": "2028-05-15T00:00:00.000",
  "sourceDataset": "currentActive",
  "sourceUrl": "https://data.cityofchicago.org/resource/uupf-x98q.json"
}

Search and filtering examples

Look up one license number

{
  "licenseNumber": "1069844",
  "sourceDataset": "all",
  "maxItems": 10
}

Build a local license-type list

{
  "licenseType": "Limited Business License",
  "zipCode": "60640",
  "sourceDataset": "currentActive",
  "maxItems": 500
}

Collect a new-issuance window

{
  "issuedFrom": "2026-08-01",
  "issuedTo": "2026-08-30",
  "sourceDataset": "all",
  "maxItems": 5000
}

How much does it cost to export Chicago business licenses?

The Actor uses pay-per-event pricing:

• one start event is charged once per run;
• one item event is charged for each saved license row;
• no charge is made for rejected, duplicate, or empty rows.

The current price is $0.005 per run plus a tiered item event. The item price is $0.009864 per record at BRONZE, with lower rates on higher Apify tiers.

Examples at the BRONZE rate:

• 1 record: approximately $0.014864 including the start event;
• 10 records: approximately $0.10364 including the start event;
• 100 records: approximately $0.99140 including the start event.

Apify applies the tier associated with your plan, and Console displays the authoritative estimate before a run.

Scheduling license monitoring

A useful recurring workflow is:

1. choose the all dataset;
2. set an issue-date or expiration-date window;
3. schedule the Actor daily, weekly, or monthly;
4. send each dataset to cloud storage or a webhook;
5. compare sourceRecordId, licenseStatus, and date fields with the previous run.

The Actor returns snapshots. It does not itself retain prior-run state, send alerts, or label changes.

Export and integration patterns

Apify datasets can be downloaded as JSON, CSV, Excel, XML, or RSS.

Common workflows include:

• Google Sheets for review queues;
• webhooks for compliance pipelines;
• Make or Zapier for no-code automation;
• Python or JavaScript for entity matching;
• BigQuery, Snowflake, or object storage for historical snapshots.

Use sourceRecordId as the primary source-row key. A license number can occur across terms or applications, so do not assume it uniquely identifies every historical row.

Run through the Apify API with cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~chicago-business-licenses/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Walgreens",
    "sourceDataset": "currentActive",
    "maxItems": 25
  }'

Keep API tokens in environment variables or a secret manager.

Run through the Apify API with JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/chicago-business-licenses').call({
  licenseType: 'Limited Business License',
  zipCode: '60640',
  sourceDataset: 'currentActive',
  maxItems: 100,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Run through the Apify API with Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/chicago-business-licenses').call(run_input={
    'issuedFrom': '2026-08-01',
    'issuedTo': '2026-08-30',
    'sourceDataset': 'all',
    'maxItems': 100,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

Use with Apify MCP

Add the Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/chicago-business-licenses"

Claude Desktop

Add this server to Claude Desktop's MCP configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/chicago-business-licenses"
    }
  }
}

Cursor

Use the same JSON server entry in Cursor's MCP settings.

VS Code

Add the same HTTP MCP server URL through your VS Code MCP extension or workspace MCP configuration.

Example prompts:

• “Find current active Chicago business licenses matching Walgreens.”
• “Export Limited Business License rows in ZIP code 60640.”
• “Collect licenses issued during August 2026 and summarize license types.”

Reliability and retries

The Actor requests the official API directly and fetches up to 1,000 rows per page.

It retries transient network, HTTP 429, and selected 5xx failures up to three times with backoff.

It does not retry deterministic validation errors or unsupported inputs.

If the official API remains unavailable after retries, the run fails instead of returning a misleading partial success.

Limits and data freshness

• The maximum input limit is 50,000 rows per run.
• Full-text search behavior is controlled by Socrata.
• Official status codes are returned as published, not translated.
• Historical rows may share a license number.
• Address and coordinates may be missing or differ from mailing information.
• Date fields reflect City records and are not legal advice.
• Dataset updates are controlled by the City of Chicago.

For very broad exports, use filters and schedule multiple bounded windows rather than repeatedly downloading unchanged records.

Troubleshooting

Why did the run return zero rows?

Remove filters one at a time and verify the selected dataset. A historical record may not be present in currentActive, and official status codes must match exactly.

Why was my date input rejected?

Use YYYY-MM-DD, and ensure the start date is not after the end date.

Why do several rows have the same license number?

The all-records dataset can include different applications, sites, or license terms. Use sourceRecordId for row-level deduplication.

Why did the run fail with a City API error?

Check the run log and retry later if the official open-data service is unavailable. The Actor already performs bounded transient retries.

Responsible use and legality

The source is a public City of Chicago open-data service. Review the City's dataset documentation and terms before use.

Use records for lawful purposes. Apply appropriate retention, security, fairness, and human-review controls when data contributes to compliance, onboarding, credit, employment, or enforcement decisions.

A public license row does not prove that a business is suitable, unsafe, compliant in every respect, or legally authorized outside the published license scope.

Related Automation Lab Actors

• NPPES NPI Registry Provider Search for US healthcare-provider identity and license fields.
• Texas Pharmacy License Lookup for Texas pharmacy credential verification.
• Chicago Food Inspections Scraper when food-safety inspection results, rather than business licenses, are the buyer job.

These Actors cover different official sources and should not be treated as equivalent registries.

FAQ

Does the Actor require a Chicago data account?

No. It uses anonymous public endpoints.

Does it require an Apify Proxy?

No. The implementation uses direct HTTP and does not expose a proxy fallback.

Can I export every Chicago license?

You can request up to 50,000 rows per run. Use bounded date or geography filters for larger recurring workflows.

Does the Actor monitor changes automatically?

Apify schedules can run it repeatedly. Comparing datasets or sending alerts must be implemented in your downstream workflow.

Are inactive licenses included?

Choose all for historical and non-current records. Choose currentActive for the City's current-active subset.

Can I search by business activity?

Use query for full-text source search. Dedicated structured filters cover business name, license type, number, status, address, geography, and dates.

Is this legal advice or an official verification certificate?

No. The Actor exports public source records and provenance. Verify material decisions with the responsible City department.