Time Atlas Python Client

Python client library for interacting with the TimeAtlas API.

Overview

The Time Atlas is a comprehensive platform for managing and analyzing historical geospatial data. This Python client provides a convenient interface for accessing TimeAtlas API endpoints and working with Research Data Entities (RDEs).

Installation

pip install time-atlas-python

Quick Start

from timeatlas import TimeAtlas

# Initialize the client
client = TimeAtlas(api_url='https://your-timeatlas-instance.com/v1')

# Fetch a single RDE object
entity = client.get_single_rde_object('historical-records', 'uuid-here')

Features

• RDE Support: Work with multiple Research Data Entity types:
  • Historical Records (HR)
  • Observations (OBS)
  • Points of Interest (POI)
  • Geometries (GEOM)
  • Datasets
  • Maps
  • Layers
  • Areas
• Type Safety: Comprehensive type hints and dataclass-based models
• Geospatial Integration: Native support for Shapely geometries

Requirements

• Python 3.12 or higher
• requests >= 2.31.0
• pandas >= 2.0.0
• shapely >= 2.0.0

Development

Setting up development environment

# Clone the repository
git clone https://github.com/epfl-timemachine/time-atlas-python.git
cd time-atlas-python

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running tests

python -m pytest

Run the complete suite with branch coverage:

python -m pytest \
  --cov=timeatlas \
  --cov-report=term-missing \
  --cov-report=html \
  --cov-report=xml

The project enforces a minimum total coverage of 95%. The HTML report is written to htmlcov/index.html, and the XML report is written to coverage.xml.

Tests use deterministic fixtures, mocked HTTP responses, temporary files, and representative RDE samples from test/data; they do not require a running TimeAtlas API.

Continuous integration

The test workflow runs the suite with coverage on Python 3.12 and 3.13 for every push and pull request. Coverage XML reports are uploaded as workflow artifacts for each supported Python version.

Code formatting

black timeatlas/

Documentation

Documentation is accessible through epfl-timemachine.github.io/time-atlas-python

License

This program is provided as open source under the GNU Affero General Public License v3 or later.