api-insee 1.2

Python helper to request Sirene Api on api.insee.fr

Python helper to request Sirene API

API Sirene give access to French companies and business database. Entities are recorded since the creation of this administrative register in 1973. To use this API you have to create an account on https://api.insee.fr/

You will find the official documentation here. All examples described here comes from the official documentation.

Installation

You can install the helper with pip

pip install api-insee

To use the api within a python script

from api_insee import ApiInsee

api = ApiInsee(
    key = # your consumer key,
    secret = # your consumer secret
)

Siren and Siret service

To get information about a siren number

data = api.siren('005520135').get()

This simple code call https://api.insee.fr/entreprises/sirene/V3/siren/005520135 and return these data :

{
  "header": {
    "statut": 200,
    "message": "OK"
  },
  "uniteLegale": {
    "siren": "005520135",
    ...
    "periodesUniteLegale": [
      {
        "dateFin": null,
        "dateDebut": "2007-11-19",
        "etatAdministratifUniteLegale": "C",
        "changementEtatAdministratifUniteLegale": true,
        "nomUniteLegale": null,
        ...
      }
      ...
    ]
  }
}

The same logic for a siret number

data = api.siret('39860733300059').get()
# call https://api.insee.fr/entreprises/sirene/V3/siret/39860733300059

Request Params

To pass url params to your request use keyword argument

data = api.siren('005520135', date='2018-01-01').get()
# https://api.insee.fr/entreprises/sirene/V3/siren/005520135?date=2018-01-01

Multicriteria search

Sirene API let you search entities using ‘q’ url parameter. For example to get all siren entities with codeCommuneEtablissement egal to 92046 you can do this request

data = api.siren(q='unitePurgeeUniteLegage:True').get()

api_insee comes with Criteria to help you to write theses requests.

import api_insee.criteria as Criteria

Criteria.Field

search on a specific field

data = api.siren(q=Criteria.Field('unitePurgeeUniteLegale', True)).get()

# will search on all entities with unitePurgeeUniteLeage=True
# /?q=unitePurgeeUniteLegale:True

you can combine several criteria together. By default the AND operator is used between each criteria.

data = api.siren(q=(
    Critera.Field('codeCommuneEtablissement', 92046),
    Criteria.Field('unitePurgeeUniteLegale', True)
)).get()

# /?q=codeCommuneEtablissement:92046 AND unitePurgeeUniteLegale:True

or you can use a dictionnary to search on multiple fields

data = api.siren(q={
    'codeCommuneEtablissement' : 92046,
    'unitePurgeeUniteLegale' : True
}).get()

# /?q=codeCommuneEtablissement:92046 AND unitePurgeeUniteLegale:True

You can use | and & logical operator to specify your requests

data = api.siren(q=(
    Criteria.Field('codeCommuneEtablissement', 92046) | Criterial.Field('unitePurgeeUniteLegale', True)
)).get()

# /?q=codeCommuneEtablissement:92046 OR unitePurgeeUniteLegale:True

- is used as NOT operator

data = api.siren(q=-Criteria.Field('codeCommuneEtablissement', 92046)).get()

# /?q=-codeCommuneEtablissement:92046

Criteria.FieldExact

To search a field on an exact value

data = api.siren(q=Criteria.FieldExact('demoninationUniteLegale','LE TIMBRE')).get()
# /?q=demoninationUniteLegale:"LE TIMBRE"

Criteria.Periodic

Periodic Field can be search with Criteria.Periodic

data = api.siren(q= Criteria.Periodic(
    Criteria.Field('activitePrincipaleUniteLegale','84.23Z') |
    Criteria.Field('activitePrincipaleUniteLegale','86.21Z')
)).get()

# /?q=periode(activitePrincipaleUniteLegale:84.23Z OR activitePrincipaleUniteLegale:86.21Z)

Criteria.Range

to search on a specific range of values

data = api.siren(q=Criteria.Range('nomUsageUniteLegale', 'DUPONT', 'DURANT'))
# /?q=nomUsageUniteLegale:[DUPONT TO DURANT]

data = api.siren(q=Criteria.Range('nomUsageUniteLegale', 'DUPONT', 'DURANT', exclude=True))
# /?q=nomUsageUniteLegale:%7BDUPONT TO DURANT%7D

Pagination

The pages() method return an iterator to let you fetch pages from the api. To specify the number of results per page use the nombre argument. Results are limited by 10000 per pages.

```python from api_insee import ApiInsee

api = ApiInsee( key = ‘YOUR-KEY’, secret = ‘YOUR-SECRET )

request = api.siren(q={ ‘categorieEntreprise’: ‘PME’ })

for (page_index, page_result) in enumerate(request.pages(nombre=1000)): # process page_result