INVENTA API Client

GitHub Repository

This project provides a Python client library for interacting with the INVENTA API.

Installation

Install the base package via pip:

pip install inventa-client

Optional Database Dependencies

Depending on what database you want to use, you can install the corresponding optional dependency:

Database	installation command	additional libraries
SQLite	pip install inventa-client	no additional dependency will be installed
PostgreSQL	pip install inventa-client[postgresql]	Installs the psycopg2 library (licensed under LGPL)
MySQL	pip install inventa-client[mysql]	Installs the mysqlclient library (licensed under GPL; may introduce additional license obligations)

If you intend to use a different database (e.g., Oracle or Microsoft SQL Server), or prefer a different database driver for PostgreSQL/MySQL, install the appropriate driver manually. Please refer to the Database URL Documentation of SQLAlchemy for details..

Usage

Database Configuration

To store data inside the database, you need to provide a valid database URL. The database URL should follow the format supported by SQLAlchemy. For example:

database URL	Your Database
sqlite:///C:\\path\\to\\database	SQLite (Windows)
sqlite:////absolute/path/to/database	SQLite (Unix/Mac)
postgresql://user:password@host:port/database	PostgreSQL
mysql://user:password@host:port/database	MySQL

See the Database URL Documentation of SQLAlchemy for more details.

API Key

To download data, you need an INVENTA API key.

Core Functions

create_schema

from inventa import create_schema

create_schema(
    db_url="...",
    enable_postgis=True
)

Creates the required database schema if it does not already exist.

• Required parameters:
  • db_url: database connection string
• Optional parameters:
  • enable_postgis: adds a PostGIS GEOMETRY(Point, 4326) column called geom to the positions table. Works only with PostgreSQL and when PostGIS is installed. (If omitted, the geom column will not be created)

validate_schema

from inventa import validate_schema

validate_schema(
    db_url="...",
    enable_postgis=True
)

Validates the database schema and logs compatibility issues.

• Required parameters:
  • db_url: database connection string
• Optional parameters:
  • enable_postgis: adds a PostGIS GEOMETRY(Point, 4326) column called geom to the positions table. Works only with PostgreSQL and when PostGIS is installed. (If omitted, the geom column will not be validated)

download_devices

from inventa import download_devices

download_devices(
    db_url="...",
    api_key="...",
    enable_progress_log=True
)

Downloads collar and trap device metadata and stores it in the database.

• Required parameters:
  • db_url: database connection string
  • api_key: INVENTA API key
• Optional parameters:
  • enable_progress_log: enables logging (if omitted, progress will not be logged)

download_events_once

from inventa import download_events_once, DataType

download_events_once(
    db_url="...",
    api_key="...",
    device_ids=[1000106,1000100],
    data_types=[DataType.POSITION, DataType.MORTALITY],
    enable_progress_log=True,
    enable_postgis=True
)

Downloads event data from the INVENTA API and stores it in the database.

• Automatically fetches only new data based on existing records
• Validates the database schema before execution
• Required parameters:
  • db_url: database connection string
  • api_key: INVENTA API key
• Optional parameters:
  • device_ids: limits data to specific devices (if omitted, data for all available devices will be downloaded)
  • data_types: filters by data types (if omitted, data for all available data types will be downloaded)
  • enable_progress_log: enables logging (if omitted, progress will not be logged)
  • enable_postgis: adds a PostGIS GEOMETRY(Point, 4326) column called geom to the positions table. Works only with PostgreSQL and when PostGIS is installed. (If omitted, the geom column will not be populated)

download_events_scheduled

from inventa import download_events_scheduled, DataType

download_events_scheduled(
    db_url="...",
    api_key="...",
    repeat_minutes=30,
    device_ids=[1000106, 1000100],
    data_types=[DataType.POSITION, DataType.MORTALITY],
    enable_progress_log=True,
    enable_postgis=True
)

Runs download_events_once on a schedule.

• The main application thread must remain active
• Required parameters:
  • db_url: database connection string
  • api_key: INVENTA API key
  • repeat_minutes: interval in minutes (>= 15)
• Optional parameters:
  • device_ids: limits data to specific devices (if omitted, data for all available devices will be downloaded)
  • data_types: filters by data types (if omitted, data for all available data types will be downloaded)
  • enable_progress_log: enables logging (if omitted, progress will not be logged)
  • enable_postgis: adds a PostGIS GEOMETRY(Point, 4326) column called geom to the positions table. Works only with PostgreSQL and when PostGIS is installed. (If omitted, the geom column will not be populated)

Direct API Access

In addition to high-level methods, the library allows direct interaction with the API.

Example: Download position data

from inventa.openapi_client import DownloadDataApi, ApiClient

api_client = ApiClient()
api_client.default_headers['x-api-key'] = "..."

dataApi = DownloadDataApi(api_client=api_client)

data = dataApi.get_position_data(
    page=0,
    filters_dto={'collarIds': [1000106,1000100]},
    gt_id=0
)

Pagination and Incremental Fetching

• The response will contain metadata about the page. Use this information to get all available pages.
• page is required
• gt_id is required:
  • Retrieve only records with an ID greater than the provided value
  • Use 0 for initial requests
  • Use the highest known ID for subsequent calls

DTOs and Models

The library provides:

• DTOs (Data Transfer Objects) for API responses
• Database models mirroring these DTOs

Example imports:

from inventa.openapi_client import PageDtoPositionDto, PositionDto
from inventa import Position

Command Line Interface

The library provides a command line interface for the Core Functions. You can run:

inventa-sync download-events --db-connection-string "..." --api-key "..."

inventa-sync download-events --db-connection-string "..." --api-key "..." --repeat-minutes 60

inventa-sync download-devices --db-connection-string "..." --api-key "..."

inventa-sync validate-schema --db-connection-string "..."

inventa-sync create-schema --db-connection-string "..."

For details on the command line interface:

inventa-sync --help

Build

To build the project, clone it from GitHub and run pip install -e ..

Legal Notice

This project is licensed with the Apache License, Version 2.0. See LICENSE.txt for details.

This project depends on third-party libraries with their own licenses. Optional dependencies may introduce additional license requirements. See NOTICE.txt for details.