Ganjoor SDKs & Libraries: Python Integration (2026)

SDKs overview

Ganjoor provides an API designed to offer programmatic access to a comprehensive database of classical Persian poetry. This enables developers to integrate poetic content, metadata, and search functionalities into their own applications and services. The primary method for interacting with the Ganjoor API programmatically is through its official Software Development Kits (SDKs) and community-contributed libraries. These tools abstract the underlying HTTP requests and JSON response parsing, allowing developers to focus on application logic rather than low-level API communication protocols. The documentation for the Ganjoor API, including details on available endpoints and data structures, can be found in the official Ganjoor API reference.

SDKs typically encapsulate API calls, handle authentication, and map API responses to native language objects, streamlining the development process. Libraries, whether official or community-driven, serve a similar purpose by providing pre-built functions and classes for specific tasks related to the Ganjoor data. The adoption of SDKs and libraries is a common practice in API ecosystems, as it reduces boilerplate code and promotes consistent interaction patterns. For example, Python's requests library is often used as a foundation for building client libraries due to its user-friendly HTTP capabilities, as detailed in the Requests library documentation.

Official SDKs by language

Currently, Ganjoor offers an official SDK primarily for the Python programming language. This SDK is designed to provide a robust and convenient interface for Python developers to interact with the Ganjoor API. It supports functionalities such as retrieving poetry, searching the database, and accessing poet information. The SDK aims to maintain parity with the features exposed by the RESTful API, ensuring developers can access the full range of Ganjoor's literary data.

The Python SDK is actively maintained and serves as the recommended method for Python-based applications requiring integration with the Ganjoor platform. Developers can expect updates that align with API changes and feature enhancements. Details on specific methods and object models within the SDK are available through the official Ganjoor developer documentation.

Installation

Installing the Ganjoor Python SDK is typically performed using pip, the standard package installer for Python. Before installation, it is recommended to ensure that you have a compatible Python version installed (Python 3.6 or newer is generally advised for modern packages) and that your pip tool is up to date.

To install the Ganjoor API client library, open your terminal or command prompt and execute the following command:

pip install ganjoor-api-client

This command will download the package from the Python Package Index (PyPI) and install it along with any necessary dependencies. After successful installation, you can import the library into your Python projects and begin making API calls. For best practices in Python development, consider using virtual environments to manage project dependencies, preventing conflicts between different projects.

Quickstart example

This quickstart example demonstrates how to use the Ganjoor Python SDK to fetch a random poem and print its details. This snippet assumes you have successfully installed the ganjoor-api-client package as described in the installation section.

First, you need to import the necessary client from the library. Then, you can instantiate the client and call its methods to interact with the Ganjoor API. While the Ganjoor API allows anonymous access for many operations, specific rate limits or premium features might require an API key. For an overview of API key management and security, refer to the OAuth 2.0 framework documentation, which specifies industry standards for delegated authorization.

from ganjoor import GanjoorClient

# Initialize the Ganjoor client
# For specific API key usage, pass it as an argument: GanjoorClient(api_key="YOUR_API_KEY")
client = GanjoorClient()

try:
    # Fetch a random poem
    print("Fetching a random poem...")
    random_poem = client.get_random_poem()

    if random_poem:
        print(f"Title: {random_poem.title}")
        print(f"Poet: {random_poem.poet.name}")
        print("Verses:")
        for verse in random_poem.verses:
            print(f"  {verse.text}")
    else:
        print("No poem found.")

except Exception as e:
    print(f"An error occurred: {e}")

This example initiates a client instance, fetches a random poem object, and then iterates through its attributes to display the title, poet's name, and individual verses. The GanjoorClient object handles the HTTP request to the Ganjoor API and parses the JSON response into a Python object structure, making it easy to access the data programmatically.

Community libraries

While Ganjoor primarily supports an official Python SDK, the open-source nature of many programming ecosystems often leads to the development of community-contributed libraries. These libraries can extend functionality, provide wrappers for other languages, or offer specialized tools built upon the Ganjoor API. Community libraries are typically developed and maintained by individual developers or groups independent of the official Ganjoor team.

Community contributions can include:

• Language wrappers: SDKs or client libraries for languages other than Python, such as JavaScript, Ruby, or Go, enabling broader integration possibilities.
• Specialized tools: Libraries focused on specific tasks, like natural language processing (NLP) on Persian poetry retrieved from Ganjoor, or tools for data visualization of poetic structures.
• Framework integrations: Adapters or plugins for popular web frameworks (e.g., Django, Flask, Node.js Express) that simplify the process of incorporating Ganjoor data into web applications.

Developers interested in exploring or contributing to community libraries should typically search platforms like GitHub, GitLab, or PyPI for projects tagged with "Ganjoor" or related terms. It is important to review the documentation, license, and activity of community libraries before integrating them into production systems, as their support and reliability can vary. The broader Python community, for instance, frequently contributes to and maintains a wide array of packages, as evidenced by discussions on forums like Python.org's community section.

As of this writing, specific widely adopted, officially endorsed community libraries beyond the unofficial Python client are not prominently listed within the official Ganjoor documentation. However, developers are encouraged to explore community forums or open-source repositories for new developments.