MACourts

A dependency-light, plain-Python Massachusetts court lookup and jurisdiction-matching library intended to be shared by docassemble-MACourts and LITEFile.

Design boundary

• Keep Shapely: Boston Municipal Court division matching is genuinely geometric.
• Avoid GeoPandas in the runtime lookup path: standard-library JSON + Shapely is enough.
• Do not import docassemble, Django, or an EFSP client in the shared layer.
• Keep geocoding in the caller. The shared layer accepts city/county/ZIP and optional coordinates.
• Own the Massachusetts court records, BMC geometry, ZIP lookup data, jurisdiction rules, and matching code.
• Return semantic court names plus reasons, with local court/session records as optional enrichment.

Package data

The maintained court catalogs and geographic lookup data are bundled inside macourts/data/ and included in installed distributions. Code accesses them through importlib.resources, so callers do not need to know a filesystem path.

Current data includes District, Housing, BMC, Superior, Juvenile, Probate and Family, Land, Appeals, and Supreme Judicial Court records; the city/county/neighborhood jurisdiction rules in jurisdiction_rules.json; Boston ward/BMC geometry; a compiled, offline Boston street-address index (bmc_addresses.sqlite) for BMC lookups with no geocoding; and the Massachusetts ZIP lookup table, used both for compatibility work and to expand ZIP-only addresses.

What it does

build_default_finder() returns a finder covering all nine Massachusetts court departments:

from macourts import Location, build_default_finder

finder = build_default_finder()

for match in finder.find(Location(city="Springfield", county="Hampden County")):
    print(match.department, "-", match.name)

The package includes:

• plain Location, CourtRecord, and CourtMatch models;
• the existing MACourts JSON court catalog, loaded from package resources;
• a composable CourtFinder over interchangeable matchers;
• jurisdiction rules for the District, Housing, Juvenile, Probate & Family, and Superior Courts, held as data rather than code, including concurrent jurisdiction, county-plus-town conjunctions, exclusions, and Boston neighborhood rules;
• BMC Shapely point-in-polygon matching, including Winthrop and nearest-polygon fallback, and the two Juvenile sessions that follow BMC division lines;
• exact-match BMC division lookup from a Boston street address alone, with no geocoding, via a compiled offline address index;
• statewide court matching;
• Suffolk County inference for addresses given as a bare Boston neighborhood;
• ZIP-code expansion for addresses that carry nothing else;
• length-gated Damerau-Levenshtein typo rescue for a misspelled city (any of the 351 municipalities or their aliases, not just Boston/Winthrop) and, inside the BMC address index, a misspelled street name — both refuse to guess when a typo is genuinely ambiguous between two different real places; see Typo rescue;
• a duck-typed adapter for docassemble Address objects without importing docassemble.

Every match carries the reasons it was returned, plus any catalog records for the court.

Package layout

Module	Contents
macourts.models	Location, CourtRecord, CourtMatch, and the shared value types
macourts.catalog	loading and indexing the packaged court records
macourts.rules	LocationRule and the data-driven RuleMatcher
macourts.boston	BMC geometry and the BMC-derived Juvenile sessions
macourts.boston_address	Boston street-address parsing and the compiled bmc_addresses.sqlite lookup
macourts.municipalities	the 351 municipalities, their counties, and the community alias index
macourts.zips	ZIP-code expansion
macourts.finder	CourtFinder, statewide courts, and build_default_finder()

Everything is re-exported from the macourts package, which is the API surface callers should import from.

Usage

See Using MACourts with addresses for installation, finder setup, field semantics, and examples covering Boston addresses, neighborhood aliases, Winthrop, statewide courts, concurrent jurisdiction, out-of-state addresses, custom city/county rules, ZIP-only input, and docassemble-style Address objects.

The jurisdiction rules themselves — their file format, the two selection modes, how they were lifted out of the legacy package, and every correction applied on top — are documented in Jurisdiction rules.

The BMC street-address index — its SAM data source, build pipeline, schema, resolution rules, and twice-yearly refresh workflow — is documented in BMC address index.

Rule data is regenerated by the scripts in scripts/; nothing at runtime depends on them.

Integration and compatibility work for the existing docassemble package is tracked in docassemble-MACourts issue #130.

Data freshness

Court locations were reconciled against the current Massachusetts Court System directories on September 3, 2026. The audit includes roster counts, address corrections, retired/new sessions, physical-vs-mailing addresses, and source links:

• Court location audit — 2026-09-03

Each current court record includes address_verified and address_source metadata. Retired court metadata used for historical docket interpretation is kept separately from current filing locations.

Filing versus appearance locations

Court records distinguish the physical/session location from the place where filings must be directed:

• location_name — physical/session identity;
• accepts_filings — whether that location itself accepts filings;
• filing_location — canonical filing location when it does not;
• appearance_locations — reverse links from a filing location to hearing/ appearance sessions.

For example, Metro South Housing Court - Stoughton Session is an appearance location but filings are directed to the Canton Session.

This metadata is deliberately separate from live Tyler/EFSP "fileability". LITEFile should use MACourts to choose the legal filing location, then confirm the current Tyler route/category hierarchy at runtime.

See the 2026-09-03 court location audit for the field semantics and the documented procedure for recovering/updating Tyler court and lower-court codes.