Skip to main content

Lovlig - lovdata API simplified.

CI Python Copier

Keep Norwegian legal documents in sync. Automatically.

Demo

Why This Exists

Lovdata publishes Norwegian laws and regulations as downloadable datasets. These datasets update frequently—laws change, new regulations appear, old ones are amended. Manually tracking what changed is tedious and error-prone.

This tool solves that:

  • Download datasets from Lovdata's API
  • Extract compressed archives automatically
  • Track exactly which files were added, modified, or removed
  • Sync incrementally—only process what changed since last run

Built for developers building legal tech, researchers analyzing legal data, or anyone who needs reliable, up-to-date Norwegian legal documents.

Important: How Lovdata's API Works

Lovdata provides bulk dataset downloads—not individual file checksums or change feeds. This means:

  • Filenames are stable identifiers - LOV-1999-07-02-63.xml never changes, even when the law's content is amended
  • No file-level change detection - The API only provides dataset-level lastModified timestamps
  • All changes are detected - Both regulatory amendments and Lovdata's editorial updates trigger change notifications

Why content hashing? Since the API doesn't provide checksums or change indicators for individual files, this tool computes xxHash for each file to detect modifications. This is the only reliable way to identify which specific documents changed.

Result: You get precise change detection, but cannot programmatically distinguish between legal amendments and editorial updates. Manual review recommended for critical changes.

Official API docs: https://api.lovdata.no/publicData

Quick Start

# Install dependencies
uv sync

# Sync everything (first run downloads all datasets)
uv run lov update

# Second run? Only processes changes
uv run lov update

That's it. Your datasets are in data/extracted/, and you know exactly what changed.

How It Works

  1. Download - Fetches dataset archives from Lovdata's API
  2. Extract - Uncompresses tar.bz2 files into organized directories
  3. Track - Computes xxHash for each file and compares against previous hashes
  4. Report - Shows exactly what changed since last run

Your Data Structure

After running lov update, you get:

data/
├── raw/
│   ├── gjeldende-lover.tar.bz2           # Downloaded archives
│   └── gjeldende-sentrale-forskrifter.tar.bz2
├── extracted/
│   ├── gjeldende-lover/
│   │   └── nl/
│   │       ├── nl-18840614-003.xml        # Extracted legal documents
│   │       ├── nl-18880623-003.xml
│   │       └── ...
│   └── gjeldende-sentrale-forskrifter/
│       └── sf/
│           └── ...
└── state.json                             # Tracks file changes

Common Tasks

See What Changed

# List all added files
uv run lov files list --status added

# See statistics
uv run lov files stats

Output example:

Dataset Statistics
┌────────────────────┬───────┬──────────┬─────────┐
│ Dataset            │ Added │ Modified │ Removed │
├────────────────────┼───────┼──────────┼─────────┤
│ gjeldende-lover    │   245 │       12 │       3 │
└────────────────────┴───────┴──────────┴─────────┘

Clean Up Removed Files

When Lovdata removes documents from their dataset, they linger in data/extracted/. Clean them up:

# Preview what would be deleted
uv run lov files prune --dry-run

# Actually remove them
uv run lov files prune

Filter Specific Datasets

Only want "gjeldende" (current) laws?

# Set in .env
LOVDATA_DATASET_FILTER=gjeldende

Force Re-download

Already have datasets but want fresh copies?

uv run lov update --force

Use as Python SDK

Simple: Just Sync Everything

from lovlig import sync_datasets

# Downloads, extracts, tracks changes - all in one call
sync_datasets()

What happens:

  1. Downloads all datasets from Lovdata API
  2. Extracts archives to data/extracted/
  3. Updates data/state.json with file hashes
  4. Shows progress bars and summary

Custom Paths and Filters

from lovlig import sync_datasets, Settings
from pathlib import Path

config = Settings(
    dataset_filter="gjeldende",              # Only current laws
    raw_data_dir=Path("my_data/archives"),
    extracted_data_dir=Path("my_data/docs"),
    max_download_concurrency=8               # Download 8 files at once
)

sync_datasets(config=config)

Query What Changed

Perfect for automation—run this after syncing to see what's new:

from lovlig import Settings, StateManager, FileStatus
from lovlig.domain.services import FileQueryService

config = Settings()
query = FileQueryService()

with StateManager(config.state_file) as state:
    # Get files added in the last sync
    new_files = query.get_files_by_filter(
        state=state.data,
        status="added",
        limit=100
    )

    for file_meta in new_files:
        print(f"New: {file_meta.path}")

    # Get statistics per dataset
    stats = query.get_dataset_statistics(state.data)
    for dataset_name, counts in stats.items():
        print(f"{dataset_name}: {counts['added']} added, {counts['modified']} modified")

Build a Processing Pipeline

from lovlig import DatasetSync, Settings
from pathlib import Path

# 1. Configure
config = Settings(dataset_filter="gjeldende")
orchestrator = DatasetSync(config)

# 2. Sync datasets
orchestrator.sync_datasets(force_download=False)

# 3. Process new files
from lovlig import StateManager
from lovlig.domain.services import FileQueryService
query = FileQueryService()

with StateManager(config.state_file) as state:
    added_files = query.get_files_by_filter(state=state.data, status="added")

    for file_meta in added_files:
        xml_path = config.extracted_data_dir / file_meta.path
        # Your processing logic here
        process_legal_document(xml_path)

Real-world use cases:

  • Legal search engine: Index new/modified documents in Elasticsearch
  • Change notifications: Email alerts when specific laws are updated
  • Data warehouse: ETL pipeline to load legal data into database
  • Analysis: Track trends in legal changes over time

See examples/sdk_usage.py for complete examples.

Configuration

Environment Variables

Create a .env file for persistent settings:

# API settings
LOVDATA_API_TIMEOUT=30

# Dataset filtering
LOVDATA_DATASET_FILTER=gjeldende    # Only "gjeldende" datasets
# LOVDATA_DATASET_FILTER=null       # All datasets

# Performance
LOVDATA_MAX_DOWNLOAD_CONCURRENCY=4  # Parallel downloads

Programmatic Configuration

from lovlig import Settings

# Override environment variables
settings = Settings(
    api_timeout=60,
    max_download_concurrency=8
)
Variable Default What It Does
LOVDATA_API_TIMEOUT 30 Seconds before API requests timeout
LOVDATA_DATASET_FILTER gjeldende Filter datasets by name (or null = all)
LOVDATA_MAX_DOWNLOAD_CONCURRENCY 4 How many files to download in parallel

Limitations

See "Important: How Lovdata's API Works" section above for context on API constraints.

  • Not real-time - Requires periodic polling (no webhooks available)
  • Storage needed - Local hashes in state.json (~5-15 MB) + extracted XML files (several GB)
  • Change detection only - Identifies that a file changed, not what or why
  • Full dataset downloads - Entire archives must be re-downloaded when any file changes

FAQ

Q: What happens if a sync is interrupted? A: State is only saved after successful completion. Just run again.

Q: Can I filter to only track specific laws? A: Yes, use the query API after syncing to filter by status, dataset name, or file patterns. See examples in "Use as Python SDK" section above.

License

MIT

Metadata

Release files for lovlig 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lovlig 0.1.3
File Size Uploaded Provenance Actions
lovlig-0.1.3.tar.gz 23.4 kB Without provenance Details for lovlig-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lovlig 0.1.3
File Interpreter ABI Platform Actions
lovlig-0.1.3-py3-none-any.whl Python 3 none any Details for lovlig-0.1.3-py3-none-any.whl

Total release size: 51.6 kB

Release files / lovlig-0.1.3.tar.gz

Download URL lovlig-0.1.3.tar.gz
Size 23.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a4812572806f5b7e7de1d8dd2e0ed5926974c70db43d4ffd19b9ecb02398312a
BLAKE2b-256 checksum
How to use checksums
94b856bf1e5f4e3e3fba05c34fa4d4d98d1c6b86b55208856af0de351747934f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.13 {"installer":{"name":"uv","version":"0.9.13"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / lovlig-0.1.3-py3-none-any.whl

Download URL lovlig-0.1.3-py3-none-any.whl
Size 28.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8c6f99ce3779f2cd29b815abecd546bbae957566f44e5ece75da6b3bc659408c
BLAKE2b-256 checksum
How to use checksums
7dbaec55aeadc5f56d174a4bf12e4f6b84d0c9775b0352fc14e13122c82b7210
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.13 {"installer":{"name":"uv","version":"0.9.13"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for lovlig 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page