The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
API-INSEE-Sirene-3.504
River stage zero No dependents
++
/ API::INSEE::Sirene

NAME

API::INSEE::Sirene - An interface for the Sirene API of INSEE

VERSION

Version 3.504

SYNOPSIS

  use API::INSEE::Sirene;

  ${API::INSEE::Sirene::CLIENT_AUTH} = 'Y2xpZW50X2tleTpjbGllbnRfc2VjcmV0'; # required: your base64 encoded credentials
  ${API::INSEE::Sirene::default_max_results} = 30; # optional
  ${API::INSEE::Sirene::proxy} = 'http://example.com:80'; # optional: if your connection require proxy, enter it here
  ${API::INSEE::Sirene::timeout} = 40; # optional

  # Examples to get informations about an establishment with SIRET number '12345678987654'
  getEstablishmentBySIRET(12345678987654, 'all');

  # or
  my $fields_that_interest_me = ['numeroVoieEtablissement', 'typeVoieEtablissement', 'libelleVoieEtablissement', 
                                 'codePostalEtablissement', 'libelleCommuneEtablissement'];
  getEstablishmentBySIRET(12345678987654, $fields_that_interest_me);

  # or
  getEstablishmentBySIRET(12345678987654, 'denominationUniteLegale');

  # or simply
  getEstablishmentBySIRET(12345678987654);

DESCRIPTION

This module allows you to interact with the Sirene API of INSEE (Institut National de la Statistique et des Études Économiques) in France.

It contains a set of functions that can perform searches on INSEE's database to get some information about french companies like their SIREN number, company name, company headquarters address, etc.

The terms "enterprise", "legal unit" and "establishment" used in this documentation are defined at the INSEE website in the following pages:

Here is the documentation with among others all fields names:

Please note that this API is french so all fields names used in function calls are in french.

REQUIRED MODULES

This module makes use of the LWP library to send http requests and JSON library to decode JSON when getting the token. Also, this module gives you responses in JSON format so you may need the JSON library.

EXPORT

These following functions are exported by default:

  • getLegalUnitBySIREN

  • getEstablishmentsBySIREN

  • getEstablishmentBySIRET

  • getEstablishmentsByName

  • getEstablishmentsByUsualName

These folowing functions are available by manual import:

  • getEstablishmentsByCriteria

  • getLegalUnitsByCriteria

  • getLegalUnitsByName

  • getLegalUnitsByUsualName

  • getUserAgentInitialized

FUNCTIONAL INTERFACE

This section describes all available features in this module.

VARIABLES

CLIENT_AUTH

Required variable so the module can connect to your INSEE account and obtain a token that allows him to send requests thereafter. The value must be your base64 encoded credentials.

The token has a limited lifetime (7 days by default but you can change it) and is automatically renewed by the API. The module gets the token only once at program launch so you need to relaunch the module to get the new token.

default_max_results

Optional variable that specifies how many results the API must return to the module. A too big value may impact response time and general performances.

This variable is set to 20 results by default.

HARD_MAX_RESULTS

Constant that specifies the max results number you can get. This value can't be increased. If you try to send a request with a higher value, the nombre parameter will be forced to HARD_MAX_RESULTS value.

proxy

Optional variable that specifies which proxy server must be used to send requests.

This variable is set to undef by default. If this variable is not set, the module uses system proxy settings.

timeout

An optional variable that specify how many seconds the client module waits for server response before giving up.

This variable is set to 20 seconds by default.

FUNCTIONS

getLegalUnitBySIREN

Search a legal unit by her SIREN number.

getEstablishmentBySIRET

Search an establishment by his SIRET number.

getEstablishmentsBySIREN

Search all establishments that are attached to the legal unit identified by this SIREN number.

getLegalUnitsByCriteria

Search all legal units matching the specified criteria.

getEstablishmentsByCriteria

Search all establishments matching the specified criteria.

getLegalUnitsByName

Search all legal units matching the specified name. (denominationUniteLegale field)

getEstablishmentsByName

Search all establishments matching the specified name. (denominationUniteLegale field)

getLegalUnitsByUsualName

Search all legal units matching the specified name. (denominationUsuelle1UniteLegale field)

getEstablishmentsByUsualName

Search all establishments matching the specified name. (denominationUsuelle1UniteLegale field)

getUserAgentInitialized

Return the user agent initialized with the token. Allows advanced users to make their own requests.

Note: All functions search and return values that are in the most recent legal unit period.

PARAMETERS

siren and siret

In the getEstablishmentBySIRET, getEstablishmentsBySIREN and getLegalUnitBySIREN functions, you must give a SIREN or a SIRET number:

  my $response_json = getLegalUnitBySIREN(123456789);
  my $response_json = getEstablishmentBySIRET(12345678987654);
  my $response_json = getEstablishmentsBySIREN(123456789);

Note: A SIREN number must be 9 digits long and a SIRET number must be 14 digits long.

criteria

In the getLegalUnitsByCriteria and getEstablishmentsByCriteria functions, you must give a hash reference of search criteria:

  # search all legal units whose acronym like 'ABC' AND whose category like 'ETI'
  my %criteria = (
    sigleUniteLegale => 'ABC',
    categorieEntreprise => 'ETI'
  );

  my $response_json = getLegalUnitsByCriteria(\%criteria);

Note: Criteria are concatened with an AND in query search. A criteria is a couple of field:value, you can use aliases defined below.

name

In the getLegalUnitsByName, getEstablishmentsByName, getLegalUnitsByUsualName and getEstablishmentsByUsualName functions, you must give a string:

    my $response_json = getLegalUnitsByName("EnterpriseName");

Note: You can enter a part or the complete name of an enterprise.

fields

All functions are taking two parameters including an optional one. The second parameter, if present, can be presented in three forms:

  my $fields_that_interest_me = ['dateCreationUniteLegale', 'sigleUniteLegale'];
  my $response_json = getLegalUnitBySIREN(123456789, $fields_that_interest_me);

  # or
  my $response_json = getLegalUnitBySIREN(123456789, 'dateCreationUniteLegale');

  # or
  my $response_json = getLegalUnitBySIREN(123456789, 'all');

You can specify an array of fields that interest you in order that the module returns to you only these fields. If you want to get only one field, you do not have to give it as an array.

When you don't specify fields like this:

  my $response_json = getLegalUnitBySIREN(123456789);

The module will not return to you all fields by default because there are too many. Instead, it returns a selection of fields that are most likely of interest to you.

If you want all fields, you have to specify it explicitly by passing the 'all' parameter.

FUNCTION RETURN

Each function listed above returns the JSON string of the response content in case of success. Else, they return a list, whose the first element is 0, and the second is the complete sent request and the response received with headers. To handling the return of these function, you can do somethink like this:

  my ($response_json, $err) = getLegalUnitBySIREN(123456789, 'dateCreationUniteLegale');

  if (!$response_json) {
      print $err;
  }

ALIAS

Some fields have an alias to be more user-friendly, here is the list of available aliases:

  my %usefull_fields_alias = (
    'nicSiege'                       => 'nicSiegeUniteLegale',
    'nom'                            => 'denominationUniteLegale',
    'dateCreation'                   => 'dateCreationUniteLegale',
    'sigle'                          => 'sigleUniteLegale',
    'categorieJuridique'             => 'categorieJuridiqueUniteLegale',
    'nomenclatureActivitePrincipale' => 'nomenclatureActivitePrincipaleUniteLegale',
    'activitePrincipale'             => 'activitePrincipaleUniteLegale',
    'numvoie'                        => 'numeroVoieEtablissement',
    'typevoie'                       => 'typeVoieEtablissement',
    'nomvoie'                        => 'libelleVoieEtablissement',
    'codePostal'                     => 'codePostalEtablissement',
    'nomCommune'                     => 'libelleCommuneEtablissement'
  );

Usage:

  my $response_json = getLegalUnitBySIREN(123456789, 'nom');

is equivalent to

  my $response_json = getLegalUnitBySIREN(123456789, 'denominationUniteLegale');

AUTHOR

Justin Fouquet <jfouquet at lncsa dot fr>

COPYRIGHT AND LICENSE

Copyright 2018 by Les Nouveaux Constructeurs

This library is free software; You can redistribute it and/or modify it under the same terms as Perl itself.