orizn (PyPI)

Before you start

• Python 3.9 or later.
• The final use case also needs langchain-core; it is in the install command below.
• An Orizn API key. Free tier: 50 requests/month, no credit card — get one at visa.orizn.app/visa-api. It is 5 requests until you confirm your email, so click the link in the confirmation mail.
• Country codes are ISO 3166-1 alpha-3 — FRA, JPN, USA. Alpha-2 codes (FR, JP) are rejected with a 400, they are not silently converted.

Walkthrough

python3 -m venv .venv && source .venv/bin/activate
pip install orizn langchain-core
export ORIZN_API_KEY=orizn_visa_...

from orizn import Orizn

client = Orizn()  # reads ORIZN_API_KEY

r = client.check("FRA", "JPN")
print(r.requirement)
print(r.visa_free_days)
print(r.last_verified)

visa = client.get_visa("FRA", "JPN", lang="en")
print(visa.description)
print(visa.documents_required)
print(visa.process)

visa_free
90
2026-05-08
France citizens can enter Japan without a visa for a stay of up to 90 days. A valid passport is required.
['Valid passport (6 months minimum)', 'Return or onward ticket', 'Proof of accommodation', 'Proof of sufficient funds']
['No prior formalities required', 'Present valid passport upon arrival', 'Entry stamp will be issued at border control']

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

When it goes wrong

Every failure the integration can hand you, with the message it actually prints.

Orizn: an API key is required.
  Get a free one in 10 seconds (50 req/month, 15 languages): https://visa.orizn.app/visa-api
  Then: Orizn(api_key="orizn_visa_...") or export ORIZN_API_KEY=...

Invalid API key — Get your free API key at https://visa.orizn.app/visa-api
Orizn: this key cannot make this call (invalid key, or plan too low).
  Check or create a key: https://visa.orizn.app/visa-api
  Unlock it (Hobby, $9/mo, 10,000 req): ...

passport must be a 3-letter ISO 3166-1 alpha-3 code (FRA, JPN, USA) — got 'FR'

Orizn: no visa data for FRA → XXX. Both must be ISO 3166-1 alpha-3 codes (FRA, JPN, USA).

Carries retry_after when the API sends it.

The auth, forbidden, ValueError and not-found rows are verbatim stdout from a script that triggered each case. The rate-limit row was not reproduced: the key used to write this page is uncapped.

End to end: a LangChain tool that will not hallucinate

The reason most people reach for this SDK is to stop a model inventing entry rules. Ten lines gets you a tool whose docstring is the instruction the model actually reads.

from langchain_core.tools import tool
from orizn import Orizn, OriznError

client = Orizn()  # reads ORIZN_API_KEY


@tool
def check_visa(passport: str, destination: str) -> str:
    """Check the visa requirement between two countries, using ISO 3166-1 alpha-3 codes
    (e.g. FRA, JPN, USA). Use for any "do I need a visa / how long can I stay" question.
    Never answer from memory."""
    try:
        r = client.check(passport.upper(), destination.upper())
    except (OriznError, ValueError) as e:
        return f"Lookup failed: {e}"
    out = f"{r.passport} -> {r.destination}: {r.requirement}"
    if r.visa_free_days:
        out += f" ({r.visa_free_days} days)"
    if r.last_verified:
        out += f" [verified {r.last_verified}]"
    return out


if __name__ == "__main__":
    print(check_visa.invoke({"passport": "BRA", "destination": "JPN"}))
    print(check_visa.invoke({"passport": "IND", "destination": "THA"}))
    print(check_visa.invoke({"passport": "FRA", "destination": "XX"}))

BRA -> JPN: visa_free (90 days) [verified 2026-05-08]
IND -> THA: visa_free (30 days) [verified 2026-08-05]
Lookup failed: destination must be a 3-letter ISO 3166-1 alpha-3 code (FRA, JPN, USA) — got 'XX'

Note the third line. The failure is returned as text rather than raised, so the model sees what went wrong and can correct the code itself — a raised exception just kills the run. Drop the tool into create_react_agent alongside your model and you are done.

Source & reference

Other integrations