INSEE API Client

A comprehensive INSEE API Python Client for accessing French data from INSEE
(Institut national de la statistique et des études économiques).

📋 Table of Contents

Features
Data Sources
Installation
Quick Start
Configuration
Usage Examples
API Reference
Project Structure
Contributing
License

✨ Features

🔒 Secure: Environment variable configuration
🏗️ Clean Architecture: Modular, maintainable and well-documented code
🛡️ Robust: Comprehensive error handling and input validation
📝 Type Safe: Full type hints throughout the codebase
🔄 Context Managers: Automatic resource cleanup
🧪 Testable: Demonstration module included
📈 Scalable: Structured to easily add new INSEE API services

Current Implementation Status:
✅ API Sirene is fully implemented (SIREN/SIRET company data)
⚠️ Other INSEE APIs have placeholder structure for future development:

Données Locales

Melodi

Metadata API

Séries Chronologiques

🌐 Data Sources

This client accesses data from INSEE - Institut national de la statistique et des études économiques

✅ Currently Implemented: API Sirene

The API Sirene module provides access to:

Legal unit data (unités légales) via SIREN codes
Establishment data (établissements) via SIRET codes
NAF codes, legal categories, creation dates
Company administrative status and employee counts

⚠️ Future Development: Other INSEE APIs

The project has placeholder structure for these additional INSEE services:

Données Locales - Local statistical data
Melodi - Economic indicators
Metadata API - Geographic metadata
Séries Chronologiques - Time series data

Contributions to implement these services are welcome!

📚 API Documentation

📦 Installation

Requirements

Python 3.8 or higher
Valid INSEE API token

Install Dependencies

pip install -r requirements.txt

requirements.txt:

requests>=2.31.0
python-dotenv>=1.0.0

Setup Credentials

Copy the example environment file:

cp .env.EXAMPLE .env

Edit .env with your credentials:

# .env
INSEE_API_TOKEN=your_insee_token

Get your API credentials:
- INSEE: Register at https://portail-api.insee.fr/user/login

🚀 Quick Start

Two Ways to Use This API Client

Option 1: Using the Demonstration Module (Batch Processing)

The included main.py module processes multiple companies from a text file:

# 1. Create a text file with SIREN/SIRET codes (one per line)
echo "552032534" > sirens.txt
echo "542051180" >> sirens.txt

# 2. Run the demonstration module
python main.py

Workflow:

Place SIREN/SIRET codes in a text file (e.g., sirens.txt)
The module reads codes line by line
For each code, it fetches:
- INSEE legal unit data (creation date, NAF code, VAT)
- INSEE establishment data (address, region)
Results are displayed with formatted output and status indicators
Summary statistics are shown at the end

Option 2: Direct API Usage in Your Code (Recommended for Integration)

You can call the API clients directly without using main.py:

from dotenv import load_dotenv
import os
load_dotenv()

from insee import UniteLegaleClient, EtablissementsClient
from config import Config

# INSEE: Get legal unit data
with UniteLegaleClient(siren="552032534") as client:
    print(f"Created: {client.date_creation()}")
    print(f"NAF: {client.code_naf()}")
    print(f"TVA: {client.tva_intracommunautaire()}")

# INSEE: Get establishment data
with EtablissementsClient(siret="55203253400054") as client:
    print(f"City: {client.ville_etablissement()}")
    print(f"Region: {client.region_etablissement()}")

Key Points:

main.py is a demonstration tool for batch processing
For production integration, import and use the clients directly in your code
Both approaches use the same underlying API clients
Direct usage gives you more control and flexibility

⚙️ Configuration

Environment Variables

Variable	Required	Description
`INSEE_API_TOKEN`	Yes	Your INSEE API access token

Validation

Check your configuration:

from api_client_insee import Config

# Validate configuration
status = Config.validate_configuration()
print(status)

# Get credentials
token = Config.get_insee_token()

📖 Usage Examples

Legal Unit Data (SIREN)

from api_client_insee import UniteLegaleClient

with UniteLegaleClient(siren="552032534") as client:
    # Basic information
    nom = client.nom_societe()
    date_creation = client.date_creation()
    naf = client.code_naf()
    categorie = client.categorie_juridique()

    # Tax information
    tva = client.tva_intracommunautaire()
    siret_siege = client.siret_siege()

    # Status
    etat = client.etat_administratif_unite_legale()  # A=Active, C=Ceased
    tranche_effectifs = client.tranche_effectifs()

Establishment Data (SIRET)

from api_client_insee import EtablissementsClient

with EtablissementsClient(siret="55203253400054") as client:
    # Address
    adresse = client.numero_voie_etablissement()
    code_postal = client.code_postal_etablissement()
    ville = client.ville_etablissement()

    # Geographic info
    departement = client.departement_etablissement()
    region = client.region_etablissement()

    # Establishment counts
    siren = client.siret[:9]
    total = client.nombre_etablissements()
    actifs = client.nombre_etablissements_actifs()
    fermes = client.nombre_etablissements_fermes()

Input Validation

from api_client_insee import SirenSiretValidator, InvalidSirenError

try:
    # Validate SIREN
    siren = SirenSiretValidator.validate_siren("552032534")

    # Validate SIRET
    siret = SirenSiretValidator.validate_siret("55203253400054")

    # Extract SIREN from SIRET
    siren_from_siret = SirenSiretValidator.extract_siren_from_siret(siret)

    # Check without raising exception
    is_valid = SirenSiretValidator.is_valid_siren("552032534")

except InvalidSirenError as e:
    print(f"Invalid format: {e}")

📚 API Reference

INSEE Clients

`UniteLegaleClient`

Legal unit data (SIREN level)
Methods: nom_societe(), date_creation(), code_naf(), tva_intracommunautaire(), etc.

`EtablissementsClient`

Establishment data (SIRET level)
Methods: ville_etablissement(), departement_etablissement(), region_etablissement(), etc.

Utilities

`Config`

Configuration management
Methods: get_insee_token(), validate_configuration()

`SirenSiretValidator`

Input validation
Methods: validate_siren(), validate_siret(), extract_siren_from_siret(), is_valid_siren(), is_valid_siret()

Exceptions

ApiClientError - Base exception
AuthenticationError - Authentication failures
ApiRequestError - API request failures
ValidationError - Input validation errors
InvalidSirenError - Invalid SIREN format
InvalidSiretError - Invalid SIRET format
DataNotFoundError - Data not found in API response

🏗️ Project Structure

api-client-insee/
├── __init__.py                  # Main package entry point
├── __version__.py              # Version information
├── config.py                    # Configuration management
├── exceptions.py                # Custom exception classes
├── main.py                      # Demonstration module
├── sirens.txt                   # Sample SIREN/SIRET codes (auto-generated)
├── requirements.txt             # Python dependencies
│
├── base/                        # Base classes
│   ├── __init__.py
│   ├── http_client.py          # Base HTTP client with error handling
│   └── authenticator.py        # Base authenticator (for future use)
│
├── utils/                       # Utilities
│   ├── __init__.py
│   └── validators.py           # SIREN/SIRET validation
│
└── insee/                       # INSEE API modules
    ├── api_sirene/             # ✓ API Sirene (implemented)
    │   ├── __init__.py
    │   ├── client.py          # UniteLegale & Etablissements clients
    │   └── builders.py        # URL builders for Sirene API
    │
    ├── donnees_locales/        # ⚠️ Placeholder for future implementation
    │   └── __init__.py
    │
    ├── melodi/                 # ⚠️ Placeholder for future implementation
    │   └── __init__.py
    │
    ├── metadata_api/           # ⚠️ Placeholder for future implementation
    │   └── __init__.py
    │
    └── series_chronologiques/  # ⚠️ Placeholder for future implementation
        └── __init__.py

Documentation:
├── README.md                    # This file
├── LICENSE                      # MIT License
├── CONTRIBUTING.md              # Development setup guide
├── .env.EXAMPLE                 # Environment variables template
├── .gitignore                   # Git ignore rules
└── .pre-commit-config.yaml      # Pre-commit hooks configuration

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Clone the repository

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```
Set up your .env file with test credentials
Run the demonstration module to verify setup

Code Style

Follow PEP 8 guidelines
Use type hints
Document all public methods with docstrings
Handle errors gracefully

📄 License

MIT License - see the LICENSE file for details.

📞 Support

For questions, bug reports, or feature requests, please use the
GitHub Issues page.

⚠️ When reporting an issue, please include:

Your Python version and environment

Steps to reproduce the problem

Any error messages or stack traces

📊 Version History

Version 2.0.0 (2025-10-27)

Complete architecture refactoring
Added environment variable configuration
Comprehensive error handling
Full type hints
Modular, maintainable codebase

Version 1.0.0 (2023-06-13)

Initial release with basic functionality
Intended for internal use by professionals in the M&A sector in France

gianpierreba/api-client-insee