Pricing

from $0.01 / 1,000 results

IBAN, VAT, BIC and ISIN validator

Validate and parse IBAN, VAT, BIC and ISIN codes offline, no API key. Checks format and check digits, then returns a table with the type, country, compact and formatted form, and a reason for any code that fails. Runs on python-stdnum, so it stays fast and reliable.

Pricing

from $0.01 / 1,000 results

Rating

0.0

(0)

Developer

Mangudäi

Actor stats

Bookmarked

Total users

Monthly active users

9 days ago

Last modified

.actor/actor.json

{
    "actorSpecification": 1,
    "name": "iban-vat-validator",
    "title": "IBAN, VAT, BIC and ISIN validator",
    "description": "Validate and parse IBAN, VAT, BIC and ISIN codes offline. No API key.",
    "version": "0.0",
    "buildTag": "latest",
    "dockerfile": "../Dockerfile",
    "meta": {
        "templateId": "python-empty"
    },
    "input": {
        "title": "IBAN, VAT, BIC and ISIN validator input",
        "type": "object",
        "schemaVersion": 1,
        "properties": {
            "codes": {
                "title": "Codes to validate",
                "type": "array",
                "description": "One or more codes to validate. Accepts IBAN, VAT, BIC or ISIN. You can also paste several codes into one line separated by commas or new lines.",
                "editor": "stringList",
                "prefill": [
                    "DE89 3704 0044 0532 0130 00",
                    "GB29 NWBK 6016 1331 9268 19",
                    "DE136695976",
                    "FR40303265045",
                    "DEUTDEFF",
                    "US0378331005"
                ]
            },
            "codeType": {
                "title": "Code type",
                "type": "string",
                "description": "Force a code type, or leave on Auto detect to guess each code from its shape.",
                "editor": "select",
                "default": "auto",
                "enum": ["auto", "iban", "vat", "bic", "isin"],
                "enumTitles": ["Auto detect", "IBAN", "VAT", "BIC / SWIFT", "ISIN"]
            }
        },
        "required": ["codes"]
    },
    "storages": {
        "dataset": {
            "actorSpecification": 1,
            "title": "Validated codes",
            "views": {
                "overview": {
                    "title": "Overview",
                    "transformation": {
                        "fields": [
                            "input",
                            "code_type",
                            "valid",
                            "country_code",
                            "country_name",
                            "compact",
                            "formatted",
                            "error"
                        ]
                    },
                    "display": {
                        "component": "table",
                        "properties": {
                            "input": {"label": "Input", "format": "text"},
                            "code_type": {"label": "Type", "format": "text"},
                            "valid": {"label": "Valid", "format": "boolean"},
                            "country_code": {"label": "Country code", "format": "text"},
                            "country_name": {"label": "Country", "format": "text"},
                            "compact": {"label": "Compact", "format": "text"},
                            "formatted": {"label": "Formatted", "format": "text"},
                            "error": {"label": "Error", "format": "text"}
                        }
                    }
                }
            }
        }
    },
    "output": {
        "actorOutputSchemaVersion": 1,
        "title": "Output",
        "properties": {
            "datasetOverview": {
                "type": "string",
                "title": "Validated codes",
                "template": "{{links.apiDefaultDatasetUrl}}/items?view=overview"
            }
        }
    }
}

my_actor/init.py

my_actor/main.py

1import asyncio
2
3from .main import main
4
5asyncio.run(main())

my_actor/main.py

1"""Offline validation and parsing of IBAN, VAT, BIC and ISIN codes.
2
3Pure offline computation via python-stdnum. No network, no API key.
4"""
5import re
6
7from stdnum import iban as _iban
8from stdnum import bic as _bic
9from stdnum import isin as _isin
10from stdnum.eu import vat as _vat
11
12try:
13    import pycountry
14    def _country_name(cc):
15        if not cc:
16            return None
17        rec = pycountry.countries.get(alpha_2=cc.upper())
18        return rec.name if rec else None
19except Exception:
20    def _country_name(cc):
21        return None
22
23CODE_TYPES = ("iban", "vat", "bic", "isin")
24
25
26def _clean(value):
27    return re.sub(r"\s+", "", (value or "").strip()).upper()
28
29
30def _detect_type(raw):
31    """Guess the code type from shape. Best effort, order matters."""
32    c = _clean(raw)
33    if _iban.is_valid(c):
34        return "iban"
35    if _bic.is_valid(c):
36        return "bic"
37    if _isin.is_valid(c):
38        return "isin"
39    if _vat.is_valid(c):
40        return "vat"
41    # shape-based fallback so invalid codes still get a sensible type
42    if re.fullmatch(r"[A-Z]{2}\d{2}[A-Z0-9]{10,30}", c):
43        return "iban"
44    if re.fullmatch(r"[A-Z]{6}[A-Z0-9]{2,5}", c):
45        return "bic"
46    if re.fullmatch(r"[A-Z]{2}[A-Z0-9]{9}\d", c):
47        return "isin"
48    return "vat"
49
50
51def validate_iban(raw):
52    c = _clean(raw)
53    out = {"code_type": "iban", "country_code": c[:2] if len(c) >= 2 else None}
54    try:
55        _iban.validate(c)
56        out["valid"] = True
57        out["compact"] = _iban.compact(c)
58        out["formatted"] = _iban.format(c)
59        out["error"] = None
60    except Exception as e:
61        out["valid"] = False
62        out["compact"] = c
63        out["formatted"] = None
64        out["error"] = str(e)
65    return out
66
67
68def validate_vat(raw):
69    c = _clean(raw)
70    out = {"code_type": "vat", "country_code": c[:2] if len(c) >= 2 else None}
71    try:
72        _vat.validate(c)
73        out["valid"] = True
74        out["compact"] = _vat.compact(c)
75        out["formatted"] = _vat.compact(c)
76        out["error"] = None
77    except Exception as e:
78        out["valid"] = False
79        out["compact"] = c
80        out["formatted"] = None
81        out["error"] = str(e)
82    return out
83
84
85def validate_bic(raw):
86    c = _clean(raw)
87    out = {"code_type": "bic", "country_code": c[4:6] if len(c) >= 6 else None}
88    try:
89        _bic.validate(c)
90        out["valid"] = True
91        out["compact"] = _bic.compact(c)
92        out["formatted"] = _bic.format(c)
93        out["error"] = None
94    except Exception as e:
95        out["valid"] = False
96        out["compact"] = c
97        out["formatted"] = None
98        out["error"] = str(e)
99    return out
100
101
102def validate_isin(raw):
103    c = _clean(raw)
104    out = {"code_type": "isin", "country_code": c[:2] if len(c) >= 2 else None}
105    try:
106        _isin.validate(c)
107        out["valid"] = True
108        out["compact"] = _isin.compact(c)
109        out["formatted"] = _isin.compact(c)
110        out["error"] = None
111    except Exception as e:
112        out["valid"] = False
113        out["compact"] = c
114        out["formatted"] = None
115        out["error"] = str(e)
116    return out
117
118
119_DISPATCH = {
120    "iban": validate_iban,
121    "vat": validate_vat,
122    "bic": validate_bic,
123    "isin": validate_isin,
124}
125
126
127def validate_code(raw, code_type="auto"):
128    """Validate one code. Returns a flat dict ready for a dataset row."""
129    raw = (raw or "").strip()
130    ctype = code_type if code_type in CODE_TYPES else _detect_type(raw)
131    result = _DISPATCH[ctype](raw)
132    row = {
133        "input": raw,
134        "code_type": result["code_type"],
135        "valid": result["valid"],
136        "country_code": result.get("country_code"),
137        "country_name": _country_name(result.get("country_code")),
138        "compact": result.get("compact"),
139        "formatted": result.get("formatted"),
140        "error": result.get("error"),
141    }
142    return row
143
144
145# ---- Apify actor entry point ----
146
147"""IBAN, VAT, BIC and ISIN validator. Apify actor entry point.
148
149Reads a list of codes from the input, validates each one offline with
150python-stdnum, and pushes one row per code to the default dataset.
151"""
152from apify import Actor
153
154
155
156async def main() -> None:
157    async with Actor:
158        actor_input = await Actor.get_input() or {}
159
160        codes = actor_input.get("codes") or []
161        if isinstance(codes, str):
162            codes = [codes]
163        code_type = actor_input.get("codeType", "auto")
164        if code_type not in CODE_TYPES:
165            code_type = "auto"
166
167        # split any newline or comma separated entries a user pasted into one field
168        expanded = []
169        for entry in codes:
170            for part in str(entry).replace(",", "\n").splitlines():
171                part = part.strip()
172                if part:
173                    expanded.append(part)
174
175        if not expanded:
176            Actor.log.warning("No codes provided in input. Nothing to validate.")
177            return
178
179        Actor.log.info(f"Validating {len(expanded)} code(s), type={code_type}.")
180
181        rows = []
182        for raw in expanded:
183            try:
184                rows.append(validate_code(raw, code_type))
185            except Exception as exc:  # never let one bad row kill the run
186                rows.append({
187                    "input": raw,
188                    "code_type": code_type if code_type in CODE_TYPES else None,
189                    "valid": False,
190                    "country_code": None,
191                    "country_name": None,
192                    "compact": None,
193                    "formatted": None,
194                    "error": f"Unexpected error: {exc}",
195                })
196
197        await Actor.push_data(rows)
198        valid_count = sum(1 for r in rows if r["valid"])
199        Actor.log.info(f"Done. {valid_count} valid, {len(rows) - valid_count} invalid.")

my_actor/py.typed

.dockerignore

.git
.mise.toml
.nvim.lua
storage

# The rest is copied from https://github.com/github/gitignore/blob/main/Python.gitignore

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
#  Usually these files are written by a python script from a template
#  before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
.pybuilder/
target/

# Jupyter Notebook
.ipynb_checkpoints

# IPython
profile_default/
ipython_config.py

# pyenv
#   For a library or package, you might want to ignore these files since the code is
#   intended to run in multiple environments; otherwise, check them in:
.python-version

# pdm
#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
#   in version control.
#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
.pdm.toml
.pdm-python
.pdm-build/

# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/

# Celery stuff
celerybeat-schedule
celerybeat.pid

# SageMath parsed files
*.sage.py

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# mkdocs documentation
/site

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# pytype static type analyzer
.pytype/

# Cython debug symbols
cython_debug/

# PyCharm
#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
#  and can be added to the global gitignore or merged into this file.  For a more nuclear
#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
.idea/

# Visual Studio Code
#  Ignores the folder created by VS Code when changing workspace settings, doing debugger
#  configuration, etc. Can be commented out to share Workspace Settings within a team
.vscode

# Zed editor
#  Ignores the folder created when setting Project Settings in the Zed editor. Can be commented out
#  to share Project Settings within a team
.zed

.gitignore

.mise.toml
.nvim.lua
storage

# The rest is copied from https://github.com/github/gitignore/blob/main/Python.gitignore

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
#  Usually these files are written by a python script from a template
#  before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
.pybuilder/
target/

# Jupyter Notebook
.ipynb_checkpoints

# IPython
profile_default/
ipython_config.py

# pyenv
#   For a library or package, you might want to ignore these files since the code is
#   intended to run in multiple environments; otherwise, check them in:
.python-version

# pdm
#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
#   in version control.
#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
.pdm.toml
.pdm-python
.pdm-build/

# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/

# Celery stuff
celerybeat-schedule
celerybeat.pid

# SageMath parsed files
*.sage.py

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# mkdocs documentation
/site

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# pytype static type analyzer
.pytype/

# Cython debug symbols
cython_debug/

# PyCharm
#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
#  and can be added to the global gitignore or merged into this file.  For a more nuclear
#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
.idea/

# Visual Studio Code
#  Ignores the folder created by VS Code when changing workspace settings, doing debugger
#  configuration, etc. Can be commented out to share Workspace Settings within a team
.vscode

# Zed editor
#  Ignores the folder created when setting Project Settings in the Zed editor. Can be commented out
#  to share Project Settings within a team
.zed

AGENTS.md

1# Apify Actors Development Guide
2
3Important: Before you begin, fill in the `generatedBy` property in the meta section of `.actor/actor.json`. Replace it with the tool and model you're currently using, such as "Claude Code with Claude Sonnet 4.5". This helps Apify monitor and improve AGENTS.md for specific AI tools and models.
4
5## What are Apify Actors?
6
7- Actors are serverless programs that run in the cloud. They're inspired by the UNIX philosophy - programs that do one thing well and can be easily combined to build complex systems.
8- Actors are programs packaged as Docker images that run in isolated containers
9
10## Core Concepts
11
12- Accept well-defined JSON input
13- Perform isolated tasks (web scraping, automation, data processing)
14- Produce structured JSON output to datasets and/or store data in key-value stores
15- Can run from seconds to hours or even indefinitely
16- Persist state and can be restarted
17
18## Do
19
20- accept well-defined JSON input and produce structured JSON output
21- use Apify SDK (`apify`) for code running ON Apify platform
22- validate input early with proper error handling and fail gracefully
23- use CheerioCrawler for static HTML content (10x faster than browsers)
24- use PlaywrightCrawler only for JavaScript-heavy sites and dynamic content
25- use router pattern (createCheerioRouter/createPlaywrightRouter) for complex crawls
26- implement retry strategies with exponential backoff for failed requests
27- use proper concurrency settings (HTTP: 10-50, Browser: 1-5)
28- set sensible defaults in `.actor/input_schema.json` for all optional fields
29- set up output schema in `.actor/output_schema.json`
30- clean and validate data before pushing to dataset
31- use semantic CSS selectors and fallback strategies for missing elements
32- respect robots.txt, ToS, and implement rate limiting with delays
33- check which tools (cheerio/playwright/crawlee) are installed before applying guidance
34- use `Actor.log` for logging (censors sensitive data)
35- implement readiness probe handler for standby Actors
36- handle the `aborting` event to gracefully shut down when Actor is stopped
37
38## Don't
39
40- do not rely on `Dataset.getInfo()` for final counts on Cloud platform
41- do not use browser crawlers when HTTP/Cheerio works (massive performance gains with HTTP)
42- do not hard code values that should be in input schema or environment variables
43- do not skip input validation or error handling
44- do not overload servers - use appropriate concurrency and delays
45- do not scrape prohibited content or ignore Terms of Service
46- do not store personal/sensitive data unless explicitly permitted
47- do not use deprecated options like `requestHandlerTimeoutMillis` on CheerioCrawler (v3.x)
48- do not use `additionalHttpHeaders` - use `preNavigationHooks` instead
49- do not assume that local storage is persistent or automatically synced to Apify Console - when running locally with `apify run`, the `storage/` directory is local-only and is NOT pushed to the Cloud
50- do not disable standby mode (`usesStandbyMode: false`) without explicit permission
51
52## Logging
53
54- **ALWAYS use `Actor.log` for logging** - This logger contains critical security logic including censoring sensitive data (Apify tokens, API keys, credentials) to prevent accidental exposure in logs
55
56### Available Log Levels
57
58The Apify Actor logger provides the following methods for logging:
59
60- `Actor.log.debug()` - Debug level logs (detailed diagnostic information)
61- `Actor.log.info()` - Info level logs (general informational messages)
62- `Actor.log.warning()` - Warning level logs (warning messages for potentially problematic situations)
63- `Actor.log.error()` - Error level logs (error messages for failures)
64- `Actor.log.exception()` - Exception level logs (for exceptions with stack traces)
65
66**Best practices:**
67
68- Use `Actor.log.debug()` for detailed operation-level diagnostics (inside functions)
69- Use `Actor.log.info()` for general informational messages (API requests, successful operations)
70- Use `Actor.log.warning()` for potentially problematic situations (validation failures, unexpected states)
71- Use `Actor.log.error()` for actual errors and failures
72- Use `Actor.log.exception()` for caught exceptions with stack traces
73
74## Graceful Abort Handling
75
76Handle the `aborting` event to terminate the Actor quickly when stopped by user or platform, minimizing costs especially for PPU/PPE+U billing.
77
78```python
79import asyncio
80
81async def on_aborting() -> None:
82    # Persist any state, do any cleanup you need, and terminate the Actor using `await Actor.exit()` explicitly as soon as possible
83    # This will help ensure that the Actor is doing best effort to honor any potential limits on costs of a single run set by the user
84    # Wait 1 second to allow Crawlee/SDK state persistence operations to complete
85    # This is a temporary workaround until SDK implements proper state persistence in the aborting event
86    await asyncio.sleep(1)
87    await Actor.exit()
88
89Actor.on('aborting', on_aborting)
90```
91
92## Standby Mode
93
94- **NEVER disable standby mode (`usesStandbyMode: false`) in `.actor/actor.json` without explicit permission** - Actor Standby mode solves this problem by letting you have the Actor ready in the background, waiting for the incoming HTTP requests. In a sense, the Actor behaves like a real-time web server or standard API server instead of running the logic once to process everything in batch. Always keep `usesStandbyMode: true` unless there is a specific documented reason to disable it
95- **ALWAYS implement readiness probe handler for standby Actors** - Handle the `x-apify-container-server-readiness-probe` header at GET / endpoint to ensure proper Actor lifecycle management
96
97You can recognize a standby Actor by checking the `usesStandbyMode` property in `.actor/actor.json`. Only implement the readiness probe if this property is set to `true`.
98
99### Readiness Probe Implementation Example
100
101```python
102# Apify standby readiness probe
103from http.server import SimpleHTTPRequestHandler
104
105class GetHandler(SimpleHTTPRequestHandler):
106    def do_GET(self):
107        # Handle Apify standby readiness probe
108        if 'x-apify-container-server-readiness-probe' in self.headers:
109            self.send_response(200)
110            self.end_headers()
111            self.wfile.write(b'Readiness probe OK')
112            return
113
114        self.send_response(200)
115        self.end_headers()
116        self.wfile.write(b'Actor is ready')
117```
118
119Key points:
120
121- Detect the `x-apify-container-server-readiness-probe` header in incoming requests
122- Respond with HTTP 200 status code for both readiness probe and normal requests
123- This enables proper Actor lifecycle management in standby mode
124
125## Commands
126
127```bash
128# Bootstrap & local development
129apify create [name]                    # Create new Actor project from a template
130apify init                             # Initialize Actor in current directory
131apify run                              # Run Actor locally with simulated platform env
132apify run --purge                      # Run after clearing previous local storage
133apify validate-schema                  # Validate .actor/input_schema.json
134
135# Authentication & account
136apify login                            # Authenticate account (token stored in ~/.apify)
137apify logout                           # Remove stored credentials
138apify info                             # Print currently authenticated account info
139
140# Deployment & remote execution
141apify push                             # Deploy Actor to platform per .actor/actor.json
142apify pull <actor>                     # Download Actor code from the platform
143apify call <actor>                     # Execute Actor remotely on the platform
144apify actors build <actor>             # Create a new build of an Actor
145apify runs ls                          # List recent runs
146
147# Discovery (search Apify Store for community Actors)
148apify actors search "<query>" --user-agent <your-agent-name>
149apify actors info <actor>              # Get details about a specific Actor
150
151# Secrets (referenced from actor.json via "@mySecret")
152apify secrets add <name> <value>       # Store a secret locally; uploaded on push
153apify secrets ls                       # List stored secret keys
154
155# Direct API access
156apify api <endpoint>                   # Send an authenticated HTTP request to Apify API
157
158# Help
159apify help                             # List all commands
160apify <command> --help                 # Get help for a specific command
161```
162
163Note: If no dedicated Actor exists for your target, search Apify Store for community options with `apify actors search "<query>" --user-agent <your-agent-name>` before building from scratch.
164
165Tip: Inside a running Actor, prefer the SDK (`Actor.get_input()`, `Actor.push_data()`, `Actor.set_value()`) over the equivalent `apify actor` runtime subcommands.
166
167## Apify Platform Environment
168
169When the Actor runs on the Apify platform, the API token is automatically available via the `APIFY_TOKEN` environment variable (note: the variable is `APIFY_TOKEN`, not `APIFY_API_TOKEN`). The Apify SDK reads it automatically, so you do not need to pass it explicitly. Locally, run `apify login` once and the SDK will use your stored credentials.
170
171## Safety and Permissions
172
173Allowed without prompt:
174
175- read files with `Actor.get_value()`
176- push data with `Actor.push_data()`
177- set values with `Actor.set_value()`
178- enqueue requests to RequestQueue
179- run locally with `apify run`
180
181Ask first:
182
183- npm/pip package installations
184- apify push (deployment to cloud)
185- proxy configuration changes (requires paid plan)
186- Dockerfile changes affecting builds
187- deleting datasets or key-value stores
188
189## Project Structure
190
191.actor/
192├── actor.json # Actor config: name, version, env vars, runtime settings
193├── input_schema.json # Input validation & Console form definition
194└── output_schema.json # Specifies where an Actor stores its output
195src/
196└── main.js # Actor entry point and orchestrator
197storage/ # Local-only storage for development (NOT synced to Cloud)
198├── datasets/ # Output items (JSON objects)
199├── key_value_stores/ # Files, config, INPUT
200└── request_queues/ # Pending crawl requests
201Dockerfile # Container image definition
202AGENTS.md # AI agent instructions (this file)
203
204## Local vs Cloud Storage
205
206When running locally with `apify run`, the Apify SDK emulates Cloud storage APIs using the local `storage/` directory. This local storage behaves differently from Cloud storage:
207
208- **Local storage is NOT persistent** - The `storage/` directory is meant for local development and testing only. Data stored there (datasets, key-value stores, request queues) exists only on your local disk.
209- **Local storage is NOT automatically pushed to Apify Console** - Running `apify run` does not upload any storage data to the Apify platform. The data stays local.
210- **Each local run may overwrite previous data** - The local `storage/` directory is reused between runs, but this is local-only behavior, not Cloud persistence.
211- **Cloud storage only works when running on Apify platform** - After deploying with `apify push` and running the Actor in the Cloud, storage calls (`Actor.push_data()`, `Actor.set_value()`, etc.) interact with real Apify Cloud storage, which is then visible in the Apify Console.
212- **To verify Actor output, deploy and run in Cloud** - Do not rely on local `storage/` contents as proof that data will appear in the Apify Console. Always test by deploying (`apify push`) and running the Actor on the platform.
213
214## Actor Input Schema
215
216The input schema defines the input parameters for an Actor. It's a JSON object comprising various field types supported by the Apify platform.
217
218### Structure
219
220```json
221{
222    "title": "<INPUT-SCHEMA-TITLE>",
223    "type": "object",
224    "schemaVersion": 1,
225    "properties": {/* define input fields here */},
226    "required": []
227}
228```
229
230### Example
231
232```json
233{
234    "title": "E-commerce Product Scraper Input",
235    "type": "object",
236    "schemaVersion": 1,
237    "properties": {
238        "startUrls": {
239            "title": "Start URLs",
240            "type": "array",
241            "description": "URLs to start scraping from (category pages or product pages)",
242            "editor": "requestListSources",
243            "default": [{ "url": "https://example.com/category" }],
244            "prefill": [{ "url": "https://example.com/category" }]
245        },
246        "followVariants": {
247            "title": "Follow Product Variants",
248            "type": "boolean",
249            "description": "Whether to scrape product variants (different colors, sizes)",
250            "default": true
251        },
252        "maxRequestsPerCrawl": {
253            "title": "Max Requests per Crawl",
254            "type": "integer",
255            "description": "Maximum number of pages to scrape (0 = unlimited)",
256            "default": 1000,
257            "minimum": 0
258        },
259        "proxyConfiguration": {
260            "title": "Proxy Configuration",
261            "type": "object",
262            "description": "Proxy settings for anti-bot protection",
263            "editor": "proxy",
264            "default": { "useApifyProxy": false }
265        },
266        "locale": {
267            "title": "Locale",
268            "type": "string",
269            "description": "Language/country code for localized content",
270            "default": "cs",
271            "enum": ["cs", "en", "de", "sk"],
272            "enumTitles": ["Czech", "English", "German", "Slovak"]
273        }
274    },
275    "required": ["startUrls"]
276}
277```
278
279## Actor Output Schema
280
281The Actor output schema builds upon the schemas for the dataset and key-value store. It specifies where an Actor stores its output and defines templates for accessing that output. Apify Console uses these output definitions to display run results.
282
283### Structure
284
285```json
286{
287    "actorOutputSchemaVersion": 1,
288    "title": "<OUTPUT-SCHEMA-TITLE>",
289    "properties": {/* define your outputs here */}
290}
291```
292
293### Example
294
295```json
296{
297    "actorOutputSchemaVersion": 1,
298    "title": "Output schema of the files scraper",
299    "properties": {
300        "files": {
301            "type": "string",
302            "title": "Files",
303            "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys"
304        },
305        "dataset": {
306            "type": "string",
307            "title": "Dataset",
308            "template": "{{links.apiDefaultDatasetUrl}}/items"
309        }
310    }
311}
312```
313
314### Output Schema Template Variables
315
316- `links` (object) - Contains quick links to most commonly used URLs
317- `links.publicRunUrl` (string) - Public run url in format `https://console.apify.com/view/runs/:runId`
318- `links.consoleRunUrl` (string) - Console run url in format `https://console.apify.com/actors/runs/:runId`
319- `links.apiRunUrl` (string) - API run url in format `https://api.apify.com/v2/actor-runs/:runId`
320- `links.apiDefaultDatasetUrl` (string) - API url of default dataset in format `https://api.apify.com/v2/datasets/:defaultDatasetId`
321- `links.apiDefaultKeyValueStoreUrl` (string) - API url of default key-value store in format `https://api.apify.com/v2/key-value-stores/:defaultKeyValueStoreId`
322- `links.containerRunUrl` (string) - URL of a webserver running inside the run in format `https://<containerId>.runs.apify.net/`
323- `run` (object) - Contains information about the run same as it is returned from the `GET Run` API endpoint
324- `run.defaultDatasetId` (string) - ID of the default dataset
325- `run.defaultKeyValueStoreId` (string) - ID of the default key-value store
326
327## Dataset Schema Specification
328
329The dataset schema defines how your Actor's output data is structured, transformed, and displayed in the Output tab in the Apify Console.
330
331### Example
332
333Consider an example Actor that calls `Actor.pushData()` to store data into dataset:
334
335```python
336# Dataset push example (Python)
337import asyncio
338from datetime import datetime
339from apify import Actor
340
341async def main():
342    await Actor.init()
343
344    # Actor code
345    await Actor.push_data({
346        'numericField': 10,
347        'pictureUrl': 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_92x30dp.png',
348        'linkUrl': 'https://google.com',
349        'textField': 'Google',
350        'booleanField': True,
351        'dateField': datetime.now().isoformat(),
352        'arrayField': ['#hello', '#world'],
353        'objectField': {},
354    })
355
356    # Exit successfully
357    await Actor.exit()
358
359if __name__ == '__main__':
360    asyncio.run(main())
361```
362
363To set up the Actor's output tab UI, reference a dataset schema file in `.actor/actor.json`:
364
365```json
366{
367    "actorSpecification": 1,
368    "name": "book-library-scraper",
369    "title": "Book Library Scraper",
370    "version": "1.0.0",
371    "storages": {
372        "dataset": "./dataset_schema.json"
373    }
374}
375```
376
377Then create the dataset schema in `.actor/dataset_schema.json`:
378
379```json
380{
381    "actorSpecification": 1,
382    "fields": {},
383    "views": {
384        "overview": {
385            "title": "Overview",
386            "transformation": {
387                "fields": [
388                    "pictureUrl",
389                    "linkUrl",
390                    "textField",
391                    "booleanField",
392                    "arrayField",
393                    "objectField",
394                    "dateField",
395                    "numericField"
396                ]
397            },
398            "display": {
399                "component": "table",
400                "properties": {
401                    "pictureUrl": {
402                        "label": "Image",
403                        "format": "image"
404                    },
405                    "linkUrl": {
406                        "label": "Link",
407                        "format": "link"
408                    },
409                    "textField": {
410                        "label": "Text",
411                        "format": "text"
412                    },
413                    "booleanField": {
414                        "label": "Boolean",
415                        "format": "boolean"
416                    },
417                    "arrayField": {
418                        "label": "Array",
419                        "format": "array"
420                    },
421                    "objectField": {
422                        "label": "Object",
423                        "format": "object"
424                    },
425                    "dateField": {
426                        "label": "Date",
427                        "format": "date"
428                    },
429                    "numericField": {
430                        "label": "Number",
431                        "format": "number"
432                    }
433                }
434            }
435        }
436    }
437}
438```
439
440### Structure
441
442```json
443{
444    "actorSpecification": 1,
445    "fields": {},
446    "views": {
447        "<VIEW_NAME>": {
448            "title": "string (required)",
449            "description": "string (optional)",
450            "transformation": {
451                "fields": ["string (required)"],
452                "unwind": ["string (optional)"],
453                "flatten": ["string (optional)"],
454                "omit": ["string (optional)"],
455                "limit": "integer (optional)",
456                "desc": "boolean (optional)"
457            },
458            "display": {
459                "component": "table (required)",
460                "properties": {
461                    "<FIELD_NAME>": {
462                        "label": "string (optional)",
463                        "format": "text|number|date|link|boolean|image|array|object (optional)"
464                    }
465                }
466            }
467        }
468    }
469}
470```
471
472**Dataset Schema Properties:**
473
474- `actorSpecification` (integer, required) - Specifies the version of dataset schema structure document (currently only version 1)
475- `fields` (JSONSchema object, required) - Schema of one dataset object (use JsonSchema Draft 2020-12 or compatible)
476- `views` (DatasetView object, required) - Object with API and UI views description
477
478**DatasetView Properties:**
479
480- `title` (string, required) - Visible in UI Output tab and API
481- `description` (string, optional) - Only available in API response
482- `transformation` (ViewTransformation object, required) - Data transformation applied when loading from Dataset API
483- `display` (ViewDisplay object, required) - Output tab UI visualization definition
484
485**ViewTransformation Properties:**
486
487- `fields` (string[], required) - Fields to present in output (order matches column order)
488- `unwind` (string[], optional) - Deconstructs nested children into parent object
489- `flatten` (string[], optional) - Transforms nested object into flat structure
490- `omit` (string[], optional) - Removes specified fields from output
491- `limit` (integer, optional) - Maximum number of results (default: all)
492- `desc` (boolean, optional) - Sort order (true = newest first)
493
494**ViewDisplay Properties:**
495
496- `component` (string, required) - Only `table` is available
497- `properties` (Object, optional) - Keys matching `transformation.fields` with ViewDisplayProperty values
498
499**ViewDisplayProperty Properties:**
500
501- `label` (string, optional) - Table column header
502- `format` (string, optional) - One of: `text`, `number`, `date`, `link`, `boolean`, `image`, `array`, `object`
503
504## Key-Value Store Schema Specification
505
506The key-value store schema organizes keys into logical groups called collections for easier data management.
507
508### Example
509
510Consider an example Actor that calls `Actor.setValue()` to save records into the key-value store:
511
512```python
513# Key-Value Store set example (Python)
514import asyncio
515from apify import Actor
516
517async def main():
518    await Actor.init()
519
520    # Actor code
521    await Actor.set_value('document-1', 'my text data', content_type='text/plain')
522
523    image_id = '123'          # example placeholder
524    image_buffer = b'...'     # bytes buffer with image data
525    await Actor.set_value(f'image-{image_id}', image_buffer, content_type='image/jpeg')
526
527    # Exit successfully
528    await Actor.exit()
529
530if __name__ == '__main__':
531    asyncio.run(main())
532```
533
534To configure the key-value store schema, reference a schema file in `.actor/actor.json`:
535
536```json
537{
538    "actorSpecification": 1,
539    "name": "data-collector",
540    "title": "Data Collector",
541    "version": "1.0.0",
542    "storages": {
543        "keyValueStore": "./key_value_store_schema.json"
544    }
545}
546```
547
548Then create the key-value store schema in `.actor/key_value_store_schema.json`:
549
550```json
551{
552    "actorKeyValueStoreSchemaVersion": 1,
553    "title": "Key-Value Store Schema",
554    "collections": {
555        "documents": {
556            "title": "Documents",
557            "description": "Text documents stored by the Actor",
558            "keyPrefix": "document-"
559        },
560        "images": {
561            "title": "Images",
562            "description": "Images stored by the Actor",
563            "keyPrefix": "image-",
564            "contentTypes": ["image/jpeg"]
565        }
566    }
567}
568```
569
570### Structure
571
572```json
573{
574    "actorKeyValueStoreSchemaVersion": 1,
575    "title": "string (required)",
576    "description": "string (optional)",
577    "collections": {
578        "<COLLECTION_NAME>": {
579            "title": "string (required)",
580            "description": "string (optional)",
581            "key": "string (conditional - use key OR keyPrefix)",
582            "keyPrefix": "string (conditional - use key OR keyPrefix)",
583            "contentTypes": ["string (optional)"],
584            "jsonSchema": "object (optional)"
585        }
586    }
587}
588```
589
590**Key-Value Store Schema Properties:**
591
592- `actorKeyValueStoreSchemaVersion` (integer, required) - Version of key-value store schema structure document (currently only version 1)
593- `title` (string, required) - Title of the schema
594- `description` (string, optional) - Description of the schema
595- `collections` (Object, required) - Object where each key is a collection ID and value is a Collection object
596
597**Collection Properties:**
598
599- `title` (string, required) - Collection title shown in UI tabs
600- `description` (string, optional) - Description appearing in UI tooltips
601- `key` (string, conditional\*) - Single specific key for this collection
602- `keyPrefix` (string, conditional\*) - Prefix for keys included in this collection
603- `contentTypes` (string[], optional) - Allowed content types for validation
604- `jsonSchema` (object, optional) - JSON Schema Draft 07 format for `application/json` content type validation
605
606\*Either `key` or `keyPrefix` must be specified for each collection, but not both.
607
608## Actor README
609
610**Always generate a README.md file as part of Actor development.** The README is the Actor's public landing page on Apify Store - it serves as SEO, first impression, documentation, and support page combined.
611
612### Required: Generate README automatically
613
614When building an Actor, always create a `README.md` in the project root. Do not wait for the user to ask for it. The README is a critical part of a complete Actor.
615
616### README structure
617
618Write in Markdown. Use H2 (`##`) for main sections (these become the table of contents) and H3 (`###`) for subsections. Do not use H1 - the Actor name is automatically the H1. Aim for at least 300 words.
619
620Include these sections in order:
621
6221. **What does [Actor name] do?** - 2-3 sentences explaining what it does, what data it extracts, and how to try it. Link to the target website. Mention Apify platform advantages (API access, scheduling, integrations, proxy rotation, monitoring).
6232. **Why use [Actor name]?** - Business use cases and benefits.
6243. **How to use [Actor name]** - Numbered step-by-step tutorial. Keep it simple and reassuring.
6254. **Input** - Describe input fields. Reference the Input tab. Optionally include a screenshot or JSON example of the input schema.
6265. **Output** - Show a simplified JSON output example. Mention "You can download the dataset in various formats such as JSON, HTML, CSV, or Excel."
6276. **Data table** - If the Actor extracts data, include a table of the main data fields it outputs.
6287. **Pricing / Cost estimation** - Set expectations on cost. Mention free tier limits if applicable. Frame as "How much does it cost to scrape [target site]?"
6298. **Tips or Advanced options** - How to optimize runs, limit compute units, improve speed or accuracy.
6309. **FAQ, disclaimers, and support** - Legality disclaimer for scrapers, known limitations, link to Issues tab for feedback, mention custom solution availability.
631
632### README best practices
633
634- Write SEO-friendly headings with relevant keywords (e.g., "How to scrape [site] data" not just "Tutorial")
635- Bold the most important words in the intro
636- The first 25% of the README matters most - front-load the value proposition
637- Match the tone to the target audience: simple language for no-code users, technical details for developers
638- Include a JSON output example showing 1-2 representative items
639- Reference these top Actors for README best practices: https://apify.com/apify/instagram-scraper and https://apify.com/compass/crawler-google-places
640- Embed YouTube video URLs on their own line (Apify Console auto-renders them)
641- Use HTML for image sizing if needed; CSS is not supported
642
643## MCP Tools
644
645### Apify MCP
646
647If the Apify MCP server is configured, use these tools for documentation:
648
649- `search-apify-docs` - Search documentation
650- `fetch-apify-docs` - Get full doc pages
651
652Otherwise, reference: `@https://mcp.apify.com/`
653
654### Playwright MCP (debugging)
655
656The Playwright MCP server is a useful tool for debugging Actors that interact with the web - it lets the agent drive a real browser to inspect pages, capture selectors, and reproduce issues.
657
658Install with the Claude Code CLI:
659
660```bash
661claude mcp add playwright npx @playwright/mcp@latest
662```
663
664Or add it manually to your MCP config:
665
666```json
667{
668    "mcpServers": {
669        "playwright": {
670            "command": "npx",
671            "args": ["@playwright/mcp@latest"]
672        }
673    }
674}
675```
676
677## Resources
678
679- [docs.apify.com/llms.txt](https://docs.apify.com/llms.txt) - Quick reference
680- [docs.apify.com/llms-full.txt](https://docs.apify.com/llms-full.txt) - Complete docs
681- [crawlee.dev](https://crawlee.dev) - Crawlee documentation
682- [whitepaper.actor](https://raw.githubusercontent.com/apify/actor-whitepaper/refs/heads/master/README.md) - Complete Actor specification

CLAUDE.md

1@AGENTS.md

Dockerfile

# First, specify the base Docker image.
# You can see the Docker images from Apify at https://hub.docker.com/r/apify/.
# You can also use any other image from Docker Hub.
FROM apify/actor-python:3.14

USER myuser

# Second, copy just requirements.txt into the Actor image,
# since it should be the only file that affects the dependency install in the next step,
# in order to speed up the build
COPY --chown=myuser:myuser requirements.txt ./

# Install the packages specified in requirements.txt,
# Print the installed Python version, pip version
# and all installed packages with their versions for debugging
RUN echo "Python version:" \
 && python --version \
 && echo "Pip version:" \
 && pip --version \
 && echo "Installing dependencies:" \
 && pip install -r requirements.txt \
 && echo "All installed Python packages:" \
 && pip freeze

# Next, copy the remaining files and directories with the source code.
# Since we do this after installing the dependencies, quick build will be really fast
# for most source file changes.
COPY --chown=myuser:myuser . ./

# Use compileall to ensure the runnability of the Actor Python code.
RUN python -m compileall -q my_actor/

# Specify how to launch the source code of your Actor.
CMD ["python", "-m", "my_actor"]

requirements.txt

1apify<4.0.0
2python-stdnum==1.20
3pycountry==24.6.1

Iban Validator API

vivid_astronaut/iban-validator

Fabio Suizu

IBAN Structure & ISO Country Codes Scraper

parseforge/iban-com-bank-codes-scraper

Retrieve global bank codes from IBAN.com including SWIFT/BIC, country, bank name, branch, city, address, and IBAN format. Validate international payment routing across 100+ countries. Export to JSON, CSV, or Excel for fintech, payments, KYC, and cross border banking compliance workflows.

ParseForge

IBAN, SWIFT Validator and Routing Number Lookup

crimson_rock/iban-swift-validator-and-routing-number-lookup

Validates IBAN and SWIFT/BIC codes and returns data for routing number for ACH and Wire.

IBAN Validator

sootesting/iban-validator

Validate International Bank Account Numbers (IBAN): checksum (mod-97), country code, length rules and formatted display. Bulk-ready, fully offline. No API keys.

soot

Commerce Validators: EU VAT (VIES), EORI, IBAN, GTIN

vaphab/commerce-validators

Bulk-validate commerce identifiers: live EU VAT (VIES) and EORI registry lookups with correct outage semantics, email/MX checks, IBAN/ABA/GTIN checksums, EU VAT rates.

Peter Darwin

EU VAT Number Validator API

andok/eu-vat-validator

Validate EU VAT numbers in bulk against the official VIES database. Extract company name, address & VAT status. Pay per validation, no subscription.

Andok

VAT Number Validator

ayeeyee/vat-number-validator

VAT Number Validator returns normalized, review-ready API data with robust inputs, consistent outputs, and pay-per-result pricing.

Virtual Footprint LLC

EU VAT Validator (VIES) Scraper

parseforge/vies-eu-vat-scraper

Validate EU VAT numbers across all 27 member states with VIES. Get company name, address, country, and validity status for any European VAT ID. Essential for cross-border invoicing, compliance checks, and B2B customer verification.

ParseForge

European Business Data MCP

roger-darwin/european-business-data-mcp

One MCP for EU business verification: SIREN/SIRET lookup, VAT validation (VIES), and IBAN checks for KYB and supplier onboarding.

Roger Darwin

🎉 Vies VAT number validation

prog-party/vies-vat-number-validation

This Vies VAT number validation Actor checks if a given VAT number is valid in the EU. A Vies check (VAT Information Exchange System check) is highly recommended and often required for VAT-exempt intra-EU transactions between businesses. Returns isValid, name and address.

Prog Party

IBAN, VAT, BIC and ISIN validator

.actor/actor.json

my_actor/__init__.py

my_actor/__main__.py

my_actor/main.py

my_actor/py.typed

.dockerignore

.gitignore

AGENTS.md

CLAUDE.md

Dockerfile

requirements.txt

You might also like

Iban Validator API

IBAN Structure & ISO Country Codes Scraper

IBAN, SWIFT Validator and Routing Number Lookup

IBAN Validator

Commerce Validators: EU VAT (VIES), EORI, IBAN, GTIN

EU VAT Number Validator API

VAT Number Validator

EU VAT Validator (VIES) Scraper

European Business Data MCP

🎉 Vies VAT number validation

.actor/actor.json

my_actor/__init__.py

my_actor/__main__.py

my_actor/main.py

my_actor/py.typed

.dockerignore

.gitignore

AGENTS.md

CLAUDE.md

Dockerfile

requirements.txt

my_actor/init.py

my_actor/main.py

my_actor/init.py

my_actor/main.py