Crawl the web, like a database query

Makra is the official client for the Makra web extraction API. Pass a URL and a small description of the data you need. Makra reads the page remotely and returns the API response as structured JSON.

This repository contains the Python and JavaScript SDKs, their shared contract, and a Python playground for a local gateway. Python is used in the examples below.

Install

Python 3.9 or later:

pip install makra

JavaScript, Node.js 18 or later:

npm install makra

Set an API key before making requests:

export MAKRA_API_KEY="your-api-key"

Extract data

schema describes the values Makra should find. The strings say what each field means on the page. Use a list with one object template for repeated content.

from makra import Makra

schema = {
    "products": [
        {
            "name": "Product title",
            "price": "Current displayed price",
            "url": "Absolute product URL",
        }
    ]
}

with Makra() as makra:
    response = makra.extract(
        ["https://example.com/category/widgets"],
        schema,
    )

print(response)

The SDK returns the full successful API body. It does not unwrap data or impose a response model.

Workflows

Need Python method Result
A response in the current request extract, schema The successful API body.
Progress while work runs extract_stream, schema_stream Server-sent lifecycle events. Retrieve the result by run ID after a terminal event.
Work that outlives this process submit_extract, submit_schema A RunHandle with wait, stream, result, and cancel.

Use schema to inspect a page before designing an extraction shape. Store a deferred run ID with your own job record. You can later call get_run, wait_for_run, stream_run_events, or get_run_result from another process.

Repository layout

Path Contents
sdk/python Python package, synchronous and asyncio clients, type hints, and tests.
sdk/javascript ESM JavaScript package with TypeScript declarations and tests.
sdk/SPEC.md Language-neutral API and SDK contract.
playground Python script for trying a local API gateway.

Local development

python -m pip install -e sdk/python
python playground/python.py https://example.com

cd sdk/python && uv run pytest

The playground defaults to http://localhost:8080 and the development API key. Override either with MAKRA_BASE_URL or MAKRA_API_KEY.

Documentation

Read the Makra documentation for setup, workflow guides, configuration, and API references. Package-specific details live in the Python README, JavaScript README, and SDK specification.