eCourts Party Case Scraper

Searches Indian eCourts cases by party name. It can also return states, districts, court complexes, and establishments.

Execution model

• One Playwright browser, one context, and one page per Actor run.
• Location selection, CAPTCHA capture, and search submission drive the official form and reuse that same browser session.
• No parallel page pool or simultaneous eCourts sessions are used.
• One sticky residential proxy route is used by default for the whole run.
• CAPTCHA attempts are clamped to 1-5.
• One sequential same-page recovery is allowed after an empty response.
• HTTP 405, 429, and 5xx responses fail fast through a circuit breaker.
• The full complex value returned by eCourts is used for set_data; the Actor no longer invents a complex-code suffix.
• The already-rendered CAPTCHA is captured from the page; the protected image URL is not fetched a second time.

Input

mode supports get_states, get_districts, get_complexes, get_establishments, and search.

Search mode accepts:

Field	Description
partyName	Required party name.
registrationYear	Optional registration-year filter.
stateCode, districtCode, complexCode	Required court location codes.
estCode	Optional establishment code.
caseStatus	Both, Pending, or Disposed.
maxCaptchaRetries	Integer from 1-5. Default: 5.
proxyConfiguration	One sticky route for the run; residential by default.

Use the location modes serially to discover current location codes. A parsed complex ID is accepted as input, but it must match a live complex returned by eCourts for the selected district.

Dataset and output

Each matched case is written as one dataset row with parsed case fields and search metadata, including searchEstCode. Zero matches correctly produce an empty case dataset.

The OUTPUT key-value-store record always reports success, totalCases, and the parsed eCourts summary, so a valid zero-result search is distinguishable from a failed run. Failures record error, upstreamStatusCode, and retryAfterMs when available.

CAPTCHA configuration

Configure CAPTCHA_API_KEY, CAPTCHA_MODEL_ID, CAPTCHA_API_URL, and CAPTCHA_API_TIMEOUT_MS as Apify environment variables/secrets.

Operational notes

• Run one Actor execution at a time when using the same eCourts route/IP.
• Do not try to bypass an HTTP 405. It means the upstream security gateway rejected the session; wait for retryAfterMs before trying again.