🏢 Wrapper Python - API Recherche d'Entreprises

Client Python complet pour l'API Recherche d'Entreprises de la DINUM, avec modèles de données structurés pour faciliter l'utilisation.

✨ Fonctionnalités

• 🔍 Recherche textuelle et géographique d'entreprises françaises
• 📊 Modèles de données structurés (dataclasses) pour un accès simplifié
• ⚡ Rate limiting automatique (respect de la limite 7 req/s)
• 🛠️ Fonctions utilitaires (validation SIRET/SIREN, formatage, etc.)
• 📖 Documentation complète avec exemples
• 🧪 Tests inclus et exemples d'utilisation

🚀 Installation

# Cloner le projet
git clone <url-du-repo>
cd py_annuaire_entreprise

# Installer les dépendances
pip install requests

📋 Utilisation rapide

Recherche simple

from py_annuaire_entreprise import APIRechercheEntrepriseClient

client = APIRechercheEntrepriseClient()

# Recherche d'entreprises
response = client.search(q="EDF", per_page=5)

for entreprise in response.results:
    print(f"🏢 {entreprise.nom_complet}")
    print(f"   SIREN: {entreprise.siren}")
    print(f"   Siège: {entreprise.siege.adresse.libelle_commune}")

Recherche par SIREN/SIRET

# Recherche par SIREN
entreprise = client.get_entreprise_by_siren("552081317")
if entreprise:
    print(f"Entreprise: {entreprise.nom_complet}")

# Informations d'un établissement par SIRET
etablissement = client.get_siret_info("55208131766522")
if etablissement:
    print(f"Adresse: {etablissement.adresse.adresse}")

Recherche géographique

# Entreprises autour d'un point GPS
response = client.near_point(
    lat=48.8566,  # Latitude Paris
    long=2.3522,  # Longitude Paris
    radius=5.0    # 5km de rayon
)

🏗️ Modèles de données

Le wrapper structure automatiquement les réponses JSON en objets Python :

response = client.search(q="EDF")
entreprise = response.results[0]

# Accès structuré et sûr aux données
print(entreprise.nom_complet)                    # Au lieu de result['nom_complet']
print(entreprise.siege.adresse.code_postal)      # Au lieu de result['siege']['code_postal']
print(len(entreprise.dirigeants))                # Au lieu de len(result.get('dirigeants', []))

# Auto-complétion dans l'IDE
# Vérification de types
# Documentation intégrée

Principaux modèles

• Entreprise : Informations complètes d'une entreprise
• Etablissement : Informations d'un établissement
• Adresse : Adresse structurée avec tous les champs
• Dirigeant : Informations sur les dirigeants
• Finances : Données financières par année
• Complements : Labels, certifications, statuts spéciaux

🛠️ Fonctions utilitaires

from py_annuaire_entreprise import (
    validate_siret, validate_siren,
    format_ca, format_resultat_net,
    get_section_activite_description
)

# Validation
if validate_siret("55208131766522"):
    print("SIRET valide")

# Formatage
print(format_ca(118690000000))  # "118 690 000 000 €"
print(format_resultat_net(-123456))  # "-123 456 €"

# Descriptions
print(get_section_activite_description("D"))  # "Production et distribution d'électricité..."

📚 Documentation de l'API

L'API Recherche d'Entreprises permet d'accéder aux données ouvertes des entreprises françaises :

• Base de données : Registre National des Entreprises (RNE) + base Sirene
• Accès : API ouverte, sans authentification
• Limite : 7 requêtes par seconde maximum
• Documentation officielle : recherche-entreprises.api.gouv.fr/docs

Principaux critères de recherche

• Textuel : Dénomination, adresse, dirigeants
• Géographique : Recherche autour d'un point GPS
• Secteur : Code NAF/APE, section d'activité
• Taille : Catégorie d'entreprise, tranche d'effectif
• Statuts : Labels (RGE, Qualiopi, Bio, etc.), ESS, associations
• Financier : Chiffre d'affaires, résultat net

📁 Structure du projet

py_annuaire_entreprise/
├── __init__.py              # API publique du package
├── client.py                # Client principal de l'API
├── models.py                # Modèles de données (dataclasses)
├── constants.py             # Constantes et fonctions utilitaires
├── examples/                # Exemples d'utilisation
│   ├── datamodel_usage.py   # Utilisation des modèles de données
│   ├── utilities_usage.py   # Utilisation des utilitaires
│   └── ...
├── documentation/           # Documentation complète de l'API
└── tests/                   # Tests unitaires

🧪 Tests et exemples

# Tests des modèles de données
python test_datamodels.py

# Exemples d'utilisation
python examples/datamodel_usage.py
python examples/utilities_usage.py

📖 Exemples avancés

Recherche avec filtres multiples

response = client.search(
    q="développement logiciel",
    section_activite_principale=["J", "M"],  # IT et services spécialisés
    departement=["75", "92", "93", "94"],    # Paris + petite couronne
    est_rge=True,                            # Certifiés RGE uniquement
    tranche_effectif_salarie=["11", "12"],   # 10-49 salariés
    per_page=25
)

Traitement par lot

# Récupérer toutes les entreprises (attention aux limites)
all_results = client.search_all_pages(
    q="développement durable",
    max_pages=10,    # Limiter à 10 pages
    max_results=100  # Ou 100 résultats max
)

Analyse des données

from py_annuaire_entreprise import get_tranches_effectif

response = client.search(q="énergie renouvelable")

# Analyser les tailles d'entreprises
tranches = get_tranches_effectif()
for entreprise in response.results:
    if entreprise.tranche_effectif_salarie:
        taille = tranches.get(entreprise.tranche_effectif_salarie, "Inconnue")
        print(f"{entreprise.nom_complet}: {taille}")

🤝 Contribution

Le projet est ouvert aux contributions ! Consultez STRUCTURE.md pour comprendre l'architecture du code.

📄 Licence

Ce projet utilise l'API Recherche d'Entreprises qui est une API ouverte de l'État français.

---

Développé par Mathdatech's Team • Documentation API officielle