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

• INSEE API Portal
• INSEE APIs Catalog
• Charte d'utilisation
• API Sirene Documentation
• API - Données locales
• Metadata API
• API - Melodi
• API - Séries chronologiques

📦 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

1. Copy the example environment file:

cp .env.EXAMPLE .env

2. Edit .env with your credentials:

# .env
INSEE_API_TOKEN=your_insee_token

3. 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:

1. Place SIREN/SIRET codes in a text file (e.g., sirens.txt)
2. The module reads codes line by line
3. For each code, it fetches:
   • INSEE legal unit data (creation date, NAF code, VAT)
   • INSEE establishment data (address, region)
4. Results are displayed with formatted output and status indicators
5. 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

1. Clone the repository
2. Create a virtual environment:

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

3. Install dependencies:

   pip install -r requirements.txt

4. Set up your .env file with test credentials
5. 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

---