# OCR Structured Extractor (AI) — Image/PDF → OCR Text + JSON (`macheta/ocr-structured-extractor`) Actor Extract OCR text and structured JSON from an image or PDF URL. Great for invoices, receipts, forms, IDs, and tables. Powered by Gemini 3 Pro. - **URL**: https://apify.com/macheta/ocr-structured-extractor.md - **Developed by:** [Anass](https://apify.com/macheta) (community) - **Categories:** AI, Developer tools - **Stats:** 42 total users, 5 monthly users, 0.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## OCR Structured Extractor (AI) — Image/PDF → OCR Text + Structured JSON ![OCR Structured Extractor icon](./assets/icon.svg) ![OCR Structured Extractor banner](./assets/banner.svg) Extract **OCR text** and **structured fields** from an **image URL** or **PDF URL** using **Gemini 3 Pro** (through the same proxy Worker used by the other AI actors in this repo). ### Keywords (SEO) ocr api, pdf ocr, image ocr, pdf to json, image to json, invoice ocr, receipt ocr, form extraction, document understanding, gemini ocr, structured extraction, data extraction, ai document parser, id card ocr, table extraction ### How it works 1. Downloads your file from `fileUrl` 2. Sends the bytes as `inlineData` to `models/{model}:generateContent` (JSON mode) 3. Parses the model response and outputs: - `text`: full OCR transcription - `data`: structured fields (either a default structure or your `extractionSchema`) ### Best for - Invoices, receipts, and utility bills (key-value extraction) - Forms and screenshots (clean OCR + structured fields) - PDFs that mix text, tables, and images (document understanding) - Identity documents (IDs, passports) and card-style layouts ### Input - `fileUrl` (string, required): Public URL to an image (png/jpg/webp) or a PDF - `instructions` (string, optional): Extraction instructions for the model - `extractionSchema` (object, optional): JSON object describing the structure you want in `data` - `model` (string, default `gemini-3-pro-preview`) - `maxBytes` (int, default `52428800`): Max size to download (PDF inline is commonly limited to 50MB) ### Supported file types - Images: `image/png`, `image/jpeg`, `image/webp` (and other `image/*` types if the server reports a correct MIME type) - Documents: `application/pdf` ### Output The Actor stores: - Dataset: one item with `fileUrl`, `mimeType`, `text`, and `data` - Key-value store exports: - `ocr.json` (full JSON output) - `ocr.txt` (OCR text only, if available) Dataset item example: ```json { "fileUrl": "https://example.com/invoice.pdf", "mimeType": "application/pdf", "model": "gemini-3-pro-preview", "text": "Invoice #INV-1002 ...", "data": { "summary": "Invoice from ACME Corp for January services.", "key_value_pairs": [ { "key": "Invoice Number", "value": "INV-1002" }, { "key": "Total", "value": "$1,249.00" } ] } } ```` ### Example input (custom schema) ```json { "fileUrl": "https://example.com/receipt.jpg", "instructions": "Extract receipt line items and totals. Return ONLY JSON.", "extractionSchema": { "merchant": "string", "date": "string", "currency": "string", "total": "string", "items": [ { "name": "string", "qty": "string", "price": "string" } ] } } ``` ### Prompt tips - For invoices/receipts: ask for `merchant`, `invoice_number`, `date`, `currency`, `subtotal`, `tax`, `total`, `items[]` - For IDs: ask for `full_name`, `document_number`, `dob`, `expiry_date` - If the document has tables, ask for `rows` with normalized columns # Actor input Schema ## `fileUrl` (type: `string`): Public URL to an image (png/jpg/webp) or a PDF document. ## `instructions` (type: `string`): Optional instructions for extraction. If empty, the Actor extracts full text plus key-value fields. ## `extractionSchema` (type: `object`): Optional JSON object describing the structure you want in the output field data. The Actor will also return full OCR text. ## `model` (type: `string`): Gemini model name to use. If the model is unavailable, the Actor may fall back. ## `maxBytes` (type: `integer`): Maximum allowed size of the downloaded file. PDFs sent inline are commonly limited to 50MB. ## Actor input object example ```json { "model": "gemini-3-pro-preview", "maxBytes": 52428800 } ``` # Actor output Schema ## `results` (type: `string`): No description ## `ocr_json` (type: `string`): No description ## `ocr_text` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("macheta/ocr-structured-extractor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("macheta/ocr-structured-extractor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call macheta/ocr-structured-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=macheta/ocr-structured-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "OCR Structured Extractor (AI) — Image/PDF → OCR Text + JSON", "description": "Extract OCR text and structured JSON from an image or PDF URL. Great for invoices, receipts, forms, IDs, and tables. Powered by Gemini 3 Pro.", "version": "1.0", "x-build-id": "vvdEO9VgMaijpMEGL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/macheta~ocr-structured-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-macheta-ocr-structured-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/macheta~ocr-structured-extractor/runs": { "post": { "operationId": "runs-sync-macheta-ocr-structured-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/macheta~ocr-structured-extractor/run-sync": { "post": { "operationId": "run-sync-macheta-ocr-structured-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "fileUrl" ], "properties": { "fileUrl": { "title": "Image or PDF URL", "type": "string", "description": "Public URL to an image (png/jpg/webp) or a PDF document." }, "instructions": { "title": "Instructions", "type": "string", "description": "Optional instructions for extraction. If empty, the Actor extracts full text plus key-value fields." }, "extractionSchema": { "title": "Extraction Schema (JSON)", "type": "object", "description": "Optional JSON object describing the structure you want in the output field data. The Actor will also return full OCR text." }, "model": { "title": "Gemini Model", "type": "string", "description": "Gemini model name to use. If the model is unavailable, the Actor may fall back.", "default": "gemini-3-pro-preview" }, "maxBytes": { "title": "Max Download Size (bytes)", "minimum": 1048576, "maximum": 104857100, "type": "integer", "description": "Maximum allowed size of the downloaded file. PDFs sent inline are commonly limited to 50MB.", "default": 52428800 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```