orizn

Official Python SDK for the Orizn Visa API.

Visa requirements for 40,027 passport-destination pairs, in 15 languages, with up to 32 data points per visa — fees, processing times, photo specs, transit visas, embassies, overstay penalties, safety advisories.

Install

pip install orizn

Quick start

from orizn import Orizn

# Free key, 10 seconds, no credit card → https://visa.orizn.app/visa-api
client = Orizn(api_key="orizn_visa_...")   # or: export ORIZN_API_KEY=...

r = client.check("FRA", "JPN")
print(r.requirement)      # "visa_free"
print(r.visa_free_days)   # 90

visa = client.get_visa("USA", "CHN", lang="fr")   # all 15 languages, free plan included
print(visa.description)
print(visa.documents_required)
print(visa.process)

That runs as-is once ORIZN_API_KEY is set. Every visa endpoint needs a key — the free tier is 100 requests/month (5 until you confirm your email).

Get a key

All 15 languages are available on every plan, free included. What paid plans add is volume and the extended data points (fees, transit, embassies, safety, …).

Methods

bulk() requires an explicit list of destinations (max 25 per call), and each destination returned counts as one request against your quota.

for row in client.bulk("FRA", ["JPN", "USA", "THA"]):
    print(row.destination, row.requirement, row.visa_free_days)

The client is a context manager, so the HTTP session gets closed:

with Orizn() as client:
    print(client.check("DEU", "BRA").requirement)

Errors

Four typed exceptions, each carrying the URL that unblocks you:

from orizn import OriznAuthError, OriznForbiddenError, OriznRateLimitError, OriznNotFoundError

try:
    visa = client.get_visa("FRA", "JPN")
except OriznAuthError:        # 401 — no key. Message links to the free key page.
    ...
except OriznForbiddenError:   # 403 — invalid key, or plan too low for this call.
    ...
except OriznRateLimitError as e:   # 429 — quota spent. e.retry_after when the API sends it.
    ...
except OriznNotFoundError:    # 404 — no data for that pair.
    ...

All four subclass OriznError, which also covers timeouts and connection failures.

Bad country codes and unsupported languages raise ValueError before the request goes out — the API bills a request before validating params, so a typo would otherwise cost you quota.

What's in get_visa()

Fields your plan doesn't include come back as None.

Core (always present)

Extended intelligence (plan-gated)

visa = client.get_visa("FRA", "JPN")

if visa.visa_fee and visa.visa_fee.single_entry:
    fee = visa.visa_fee.single_entry
    print(f"Single entry: {fee.amount} {fee.currency}")

if visa.transit_visa:
    for hub in visa.transit_visa.hubs:
        print(f"{hub.airport} ({hub.city}): {hub.transit_free_hours}h transit-free")

if visa.safety:
    print(f"Advisory level: {visa.safety.level}")

if visa.embassy:
    for e in visa.embassy.visa_application_embassy:   # where to apply
        print(f"{e.name} ({e.city}) — {e.phone}")

print(visa.entry_by_mode.air.get("visa_free_days") if visa.entry_by_mode else None)

All types are exported: from orizn import VisaData, TransitVisa, EmbassyData, ....

Languages

fr en es pt de it ja ko zh ru ar hi th vi tl — the tuple is exported as orizn.LANGUAGES.

Tests

python tests/test_client.py                 # offline, no key
ORIZN_API_KEY=... python tests/test_client.py   # + a live smoke test (~5 requests)

Offline, a fake session replays payloads captured from production. With a key set, the same run also hits the real API, so a schema drift shows up instead of silently decoding to None.

Feedback

Building a travel agent or visa tool? Tell us what you need — api@orizn.app.

Links

• Get a free API key
• API docs
• MCP server
• npm SDK