🎓 PDDIKTI API Python Library

An unofficial Python wrapper for the Indonesian Higher Education Database (PDDIKTI, Kemdiktisaintek).

pddiktipy gives you a clean, typed interface to student, lecturer, university, and study-program data from PDDIKTI, with connection pooling, retries, validation, and comprehensive error handling.

📋 Table of Contents

• Features
• Installation
• Cloudflare access (read this first)
• Quick Start
• Error Handling
• Documentation
• Requirements
• Testing
• Contributing
• License

🚀 Features

• ✅ 70+ endpoints — search, details, statistics, and visualizations
• ✅ Full type hints for good editor support
• ✅ Robust error handling with custom exceptions and input validation
• ✅ Context manager support for clean resource management
• ✅ Connection pooling & retries out of the box
• ✅ Transparent AES-256 decryption for the encrypted search endpoint

📦 Installation

pip install pddiktipy

To let the client read the Cloudflare clearance cookie from your local browser automatically (see below), install the optional extra:

pip install "pddiktipy[auto]"

🚨 Cloudflare access (read this first)

The upstream API (https://pddikti.kemdiktisaintek.go.id/api) is protected by a Cloudflare Turnstile challenge. A plain HTTP client always receives 403, so api() with no arguments will not work on its own. Only a real browser can pass the challenge — even automated browsers (Selenium/Playwright) are blocked.

You therefore need to supply Cloudflare clearance in one of three ways.

Option A — auto cookie (easiest, on your own machine)

pip install "pddiktipy[auto]"

1. Open https://pddikti.kemdiktisaintek.go.id in Chrome or Edge and complete the "Verify you are human" check once.
2. Run your code — the client reads the cf_clearance cookie for you:

from pddiktipy import api

with api(auto_cookie=True) as client:
    print(client.get_pt_count())   # {'status': 'success', 'data': {'jumlah': 4416}}

Option B — paste the cookie manually (works on servers / other machines)

1. Open the site in your browser and pass the check.
2. Open DevTools (F12) → Application → Cookies → select the site → copy the value of cf_clearance.
3. In DevTools → Network, click any request → Headers → copy the User-Agent (the cookie is bound to it).

from pddiktipy import api

client = api(
    cf_clearance="PASTE_CF_CLEARANCE_HERE",
    user_agent="PASTE_YOUR_BROWSER_USER_AGENT_HERE",
)
print(client.get_pt_count())

Option C — run your own solver proxy (most stable for production)

Point base_url at a service that solves Cloudflare for you (for example a FlareSolverr-backed proxy that forwards to the PDDIKTI upstream):

from pddiktipy import api

client = api(base_url="http://localhost:8080/api")
print(client.get_pt_count())

Note: cf_clearance is bound to your IP and User-Agent and expires after ~30 minutes. For long-running, unattended use, prefer Option C.

⚡ Quick Start

from pddiktipy import api
from pprint import pprint

# See "Cloudflare access" above for how to provide clearance.
with api(auto_cookie=True) as client:
    # Search across all categories (payload is decrypted for you)
    results = client.search_all("Universitas Diponegoro")
    pprint(results)

    # Search a specific category
    students = client.search_mahasiswa("Ilham Riski Wibowo")
    pprint(students)

    # Aggregate statistics
    print(client.get_pt_count())          # number of universities
    print(client.get_mahasiswa_count())   # number of students

A runnable example lives in examples/quickstart.py.

⚠️ Error Handling

By default, API methods log and return None on failure rather than raising, so everyday calls stay simple:

with api(auto_cookie=True) as client:
    result = client.search_mahasiswa("")   # invalid keyword -> logs and returns None
    if result is None:
        print("No result / request failed")

The lower-level exceptions are still available if you build on top of the helper:

from pddiktipy.exceptions import (
    ValidationError, APIConnectionError, APITimeoutError,
    APIRateLimitError, APIResponseError, PDDIKTIError,
)

If the upstream returns a Cloudflare challenge, the client raises an APIResponseError whose message explains exactly how to supply clearance.

📚 Documentation

➡️ API Documentation — every method, with parameters, examples, and response field descriptions.

📋 Requirements

• Python 3.7+
• requests
• cryptography
• browser_cookie3 (optional, only for auto_cookie=True)

🧪 Testing

🧪 Testing Guide — how to run the test suite.

Offline tests (no network) can be run directly:

python -m pytest tests/test_crypto_and_endpoints.py -q

🤝 Contributing

🤝 Contributing Guide — how to contribute.

📄 License

Distributed under the MIT License.

📞 Support & Contact

• Author: Ilham Riski Wibowo
• Issues: GitHub Issues
• PyPI: pddiktipy

⭐ If this library helps your project, please consider starring it on GitHub!