Skip to content
Analog Docs

Python API reference

Most Python work starts with analog(url), which fetches, extracts, and saves a page in one call. Use assess(url) when you want to check the page’s fit first. The Fetching and Results guides explain the task-level choices; this page is the compact lookup for names and parameters.

AnalogResponse contains the page’s ordered physical structured_content Sections, high-confidence collections, outline, navigation, warnings, and saved-result handle. A Collection provides one identity-deduplicated local records view over compatible Sections while keeping every physical placement available. Read response.preview() first, then select the Collection, Section, or narrowing method your task needs.

Extract and assess

Section titled “Extract and assess”

analog

Section titled “analog”
analog(
    url: str,
    *,
    html: str | None = None,
    fetcher: Fetcher | None = None,
    base_url: str | None = None,
    save: bool = True,
    reveal_all: bool = True,
    load_all: bool = False,
    expand_all: bool = False,
    mode: Mode = 'auto',
    pages: int = 1,
    allow_private: bool = False,
) -> AnalogResponse

Turn a webpage into something you can understand and use.

assess

Section titled “assess”
assess(
    url: str,
    *,
    html: str | None = None,
    fetcher: Fetcher | None = None,
    reveal_all: bool = True,
    load_all: bool = False,
    expand_all: bool = False,
    probe_feed: bool = True,
    allow_private: bool = False,
) -> FitAssessment

Assess whether a page is worth a structured Analog extraction.

Client and fetchers

Section titled “Client and fetchers”

Client

Section titled “Client”
Client(
    *,
    base_url: str | None = None,
    timeout: float = 60.0,
    max_retries: int = 3,
    http_client: httpx.Client | None = None,
)

Synchronous Analog client.

Client.extract

Section titled “Client.extract”
Client.extract(
    *,
    html: str,
    url: str,
    reuse_token: str | None = None,
    offer_reuse: bool = False,
) -> AnalogResponse

Send HTML to the backend for extraction.

Client.info

Section titled “Client.info”
Client.info() -> InfoResponse

Fetch backend version + wire schema version. Lets the caller warn on skew.

Client.submit_feedback

Section titled “Client.submit_feedback”
Client.submit_feedback(payload: FeedbackRequest) -> FeedbackResponse

Send one feedback submission and return its durable receipt.

Browser

Section titled “Browser”
Browser(
    *,
    timeout: float = 30.0,
    wait_for: str | None = None,
    wait_for_load_state: Literal['commit', 'domcontentloaded', 'load', 'networkidle'] = 'load',
    additional_wait_ms: int = 0,
    scroll: bool = True,
    reveal_all: bool = True,
    load_all: bool = False,
    expand_all: bool = False,
    page_batches: int = 1,
    max_scroll_iterations: int | None = None,
    headless: bool = True,
    user_agent: str | None = None,
    use_system_chrome: bool = False,
    robots_checker: RobotsChecker | None = None,
    allow_private: bool = False,
)

JS-aware analog.fetcher.Fetcher powered by Playwright.

HttpFetcher

Section titled “HttpFetcher”
HttpFetcher(
    *,
    timeout: float = 30.0,
    user_agent: str | None = None,
    robots_checker: RobotsChecker | None = None,
    max_response_bytes: int | None = 26214400,
    allow_private: bool = False,
)

Minimal httpx-based fetcher — single GET, follows redirects.

RobotsChecker

Section titled “RobotsChecker”
RobotsChecker(
    user_agent: str,
    *,
    cache_ttl_seconds: float = 86400,
    unreachable_retry_seconds: float = 300,
    timeout: float = 10.0,
    allow_private: bool = False,
)

Checks URLs against per-origin robots.txt rules.

RobotsChecker.check

Section titled “RobotsChecker.check”
RobotsChecker.check(url: str) -> None

Raise RobotsTxtDisallowedError if robots.txt disallows this URL.

RobotsChecker.sitemaps

Section titled “RobotsChecker.sitemaps”
RobotsChecker.sitemaps(url: str) -> list[str] | None

The Sitemap: URLs declared by the origin’s robots.txt.

Read a response

Section titled “Read a response”

AnalogResponse.preview

Section titled “AnalogResponse.preview”
AnalogResponse.preview(*, complete: bool = False, voice: Voice = 'python') -> str

Token-optimized page overview for LLM agents.

AnalogResponse.find

Section titled “AnalogResponse.find”
AnalogResponse.find(
    pattern: str | re.Pattern[str],
    field: str | None = None,
) -> list[dict[str, FieldValue]]

Search every section’s records for matching values.

AnalogResponse.sections_by_kind

Section titled “AnalogResponse.sections_by_kind”
AnalogResponse.sections_by_kind(kind: str) -> list[Section]

Every extracted section classified as kind, in document order.

AnalogResponse.section

Section titled “AnalogResponse.section”
AnalogResponse.section(label: str) -> Section | None

The extracted section whose label matches, or None.

AnalogResponse.to_dataframe

Section titled “AnalogResponse.to_dataframe”
AnalogResponse.to_dataframe() -> pd.DataFrame

Every record on the page as one pandas DataFrame.

AnalogResponse.to_json

Section titled “AnalogResponse.to_json”
AnalogResponse.to_json() -> str

Self-contained JSON serialization of the result.

AnalogResponse.to_yaml

Section titled “AnalogResponse.to_yaml”
AnalogResponse.to_yaml() -> str

YAML serialization of the extracted records.

AnalogResponse.to_csv

Section titled “AnalogResponse.to_csv”
AnalogResponse.to_csv() -> str

CSV serialization of the extracted records.

Collection.numeric

Section titled “Collection.numeric”
Collection.numeric(field: str) -> list[float | None]

Normalized numeric values for each canonical record, when available.

Section.preview

Section titled “Section.preview”
Section.preview(*, complete: bool = False, voice: Voice = 'python') -> str

Token-optimized overview of this section.

Section.find

Section titled “Section.find”
Section.find(
    pattern: str | re.Pattern[str],
    field: str | None = None,
) -> list[dict[str, FieldValue]]

Search this section’s records for matching values.

Section.numeric

Section titled “Section.numeric”
Section.numeric(field: str) -> list[float | None]

The normalized numeric column for field, aligned with records.

Section.to_dataframe

Section titled “Section.to_dataframe”
Section.to_dataframe() -> pd.DataFrame

This section’s records as a pandas DataFrame.

Section.field_stats

Section titled “Section.field_stats”
Section.field_stats() -> list[FieldStat]

Per-field statistics for this section — the data behind describe.

Saved-result store

Section titled “Saved-result store”

save

Section titled “save”
save(
    response: AnalogResponse,
    *,
    url: str,
    fetch_settings: FetchSettings | None = None,
) -> str

Persist response as a new artifact and return its handle.

open

Section titled “open”
open(handle: str) -> AnalogResponse

Re-hydrate a saved result by handle — no fetch, no HTML.

latest

Section titled “latest”
latest() -> AnalogResponse | None

Re-hydrate the most recently created result, or None if empty.

history

Section titled “history”
history() -> list[ResultMeta]

All saved results, newest first.

store_stats

Section titled “store_stats”
store_stats() -> StoreStats

The store’s disk footprint: entry count, total bytes, and the caps.

latest_handle

Section titled “latest_handle”
latest_handle() -> str | None

The handle of the most recently created result, or None.

delete

Section titled “delete”
delete(handle: str) -> None

Remove a saved result. Idempotent — a missing handle is a no-op.

delete_many

Section titled “delete_many”
delete_many(predicate: Callable[[ResultMeta], bool]) -> list[str]

Delete every saved result whose meta satisfies predicate.

rename

Section titled “rename”
rename(handle: str, name: str) -> None

Attach a friendly name to a saved result.

rename_fields

Section titled “rename_fields”
rename_fields(
    handle: str,
    renames: dict[str, str],
    *,
    sticky: bool = True,
) -> AnalogResponse

Rename fields on a saved result, persisted in place.

reorder_fields

Section titled “reorder_fields”
reorder_fields(handle: str, order: list[str], *, sticky: bool = True) -> AnalogResponse

Put order’s fields first on a saved result, persisted in place.

results_dir

Section titled “results_dir”
results_dir() -> Path

Resolve the directory holding saved result artifacts.

Complete root export inventory

Section titled “Complete root export inventory”

  • Primary calls: analog, assess

  • Client and fetching: Browser, BrowserRecipe, Client, Fetcher, FetchResult, HttpFetcher, RobotsChecker

  • Results and response models: AnalogResponse, BotProtectionInfo, BrowseAction, Collection, ErrorResponse, ExtractRequest, FeedbackRequest, FeedbackResponse, FieldInfo, FieldStat, FieldValue, FitAssessment, InfoResponse, NavNode, NavRegion, OutlineNode, PageSweep, PaginationInfo, RateLimitInfo, ResponseWarning, Section

  • Saved results: FetchSettings, ResultMeta, StoreStats, delete, delete_many, history, latest, latest_handle, open, rename, rename_fields, reorder_fields, results_dir, save, store_stats

  • Exceptions: AnalogAPIError, AnalogAccountDeactivatedError, AnalogAuthError, AnalogConnectionError, AnalogError, AnalogIncompatibleSectionsError, AnalogRateLimitError, AnalogVersionSkewError, FetchBlockedError, FetchError, InvalidResultNameError, ResultNameInUseError, ResultNotFoundError, ResultSchemaDriftError, RobotsTxtDisallowedError, RobotsTxtUnreachableError

  • Constants and progress: DEFAULT_ROBOTS_CACHE_TTL_SECONDS, DEFAULT_UNREACHABLE_RETRY_SECONDS, FEEDBACK_LABELS, SCHEMA_VERSION, __version__, noop_progress, set_progress

Section titled “Related guides”