API::INSEE::Sirene - An interface for the Sirene API of INSEE
Version 4.04
use API::INSEE::Sirene; my $sirene = API::INSEE::Sirene->new('Y29uc3VtZXIta2V5OmNvbnN1bWVyLXNlY3JldA=='); # your base64 encoded credentials $sirene->setMaxResults(30); # Examples to get information about an establishment with SIRET number '12345678987654' $sirene->getEstablishmentBySIRET(12345678987654, 'all'); # or my $fields_that_interest_me = ['numeroVoieEtablissement', 'typeVoieEtablissement', 'libelleVoieEtablissement', 'codePostalEtablissement', 'libelleCommuneEtablissement']; $sirene->getEstablishmentBySIRET(12345678987654, $fields_that_interest_me); # or $sirene->getEstablishmentBySIRET(12345678987654, 'denominationUniteLegale'); # or simply $sirene->getEstablishmentBySIRET(12345678987654); # you can also perform searches whith a partial SIREN/SIRET number using search functions: $sirene->searchEstablishmentBySIRET(1234567898); $sirene->searchLegalUnitBySIREN(123456);
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:
Enterprise definition:
https://www.insee.fr/en/metadonnees/definition/c1496
Legal unit definition:
https://www.insee.fr/en/metadonnees/definition/c1044
Establishment definition:
https://www.insee.fr/en/metadonnees/definition/c1377
Here is the documentation with among others all fields names:
https://api.insee.fr/catalogue/site/themes/wso2/subthemes/insee/pages/item-info.jag?name=Sirene&version=V3&provider=insee
Please note that this API is french so all fields names used in function calls are in french, including the aliases.
This module has been tested with 3.9 INSEE API version.
Carp
JSON
List::Util
HTTP::Request::Common
HTTP::Status version < 6.26
LWP::UserAgent
POSIX::strftime
Switch
The API's default number of results for each request. You can override it with the setMaxResults method. A too big value may impact response time and general performances.
setMaxResults
This constant is set to 20 results.
This constant specifies how many seconds the client module has to wait for server response before giving up. You can override it with the setTimeout method.
setTimeout
This constant is set to 20 seconds.
The maximum number of results that you can get. This value can't be increased (restricted by API). If you try to send a request with a higher value, the nombre parameter will be forced to HARD_MAX_RESULTS value.
nombre
This constant is set to 1000 results.
A SIREN number has a maximum length of 9 digits.
A SIREN number has a maximum length of 14 digits.
In order to avoid useless requests with too short SIREN/SIRET numbers, the module requires at least 3 digits to allow you performing a search.
You can use this method to build more specific criteria:
my $criteria1 = $sirene->getCustomCriteria('numeroVoieEtablissement', 42);
You can choose between three search modes: 'exact', 'begin' or 'approximate' match. Default is 'approximate'.
my $criteria2 = $sirene->getCustomCriteria('libelleVoieEtablissement', 'avenue', undef, 'exact');
Important: You must specify the endpoint to be reached before calling the getCustomCriteria method using setCurrentEndpoint
getCustomCriteria
setCurrentEndpoint
$sirene->setCurrentEndpoint('siret');
Search all establishments matching the specified name. (denominationUniteLegale field)
Search all the establishments attached to a legal unit identified by a SIREN number.
Search an establishment by its SIRET number.
Search all establishments matching the specified name. (denominationUsuelle1UniteLegale field)
Search all legal units matching the specified name. (denominationUniteLegale field)
Search all legal units matching the specified name. (denominationUsuelle1UniteLegale field)
Search a legal unit by its SIREN number.
This method is used to perform a search with a custom criteria built using the getCustomCriteria method.
Before using this method, you have to specify the targeted endpoint by calling the setCurrentEndpoint method.
my $final_criteria = "$criteria1 OR $criteria2"; my ($err, $result) = $sirene->$sirene->searchByCustomCriteria($final_criteria);
Search all establishments which SIRET number is begining by the number given in parameter.
Search all legal units which SIREN number is begining by the number given in parameter.
You can set your credentials separately from the instantiation if you need to (but this must be done before any call to the search methods).
$sirene->setCredentials('Y29uc3VtZXIta2V5OmNvbnN1bWVyLXNlY3JldA==');
Used to specifie the reached API endpoint.
Enables the debug mode. When enabled, all the requests built by the module are displayed instead of being sent.
$sirene->setDebugMode(1);
Used to override the DEFAULT_MAX_RESULTS value to get more results, within the limit of HARD_MAX_RESULTS value.
$sirene->setMaxResults(30);
You can define which proxy server must be used to send requests. The system's proxy settings are used by default.
$sirene->setProxy('https://myproxy.com:1234');
Used to override the DEFAULT_TIMEOUT value.
$sirene->setTimeout(40);
All search methods take an optional $desired_fields parameter that comes in three differents flavours:
$desired_fields
my $fields_that_interest_me = ['dateCreationUniteLegale', 'sigleUniteLegale']; my $response_json = $sirene->getLegalUnitBySIREN(123456789, $fields_that_interest_me); # or my $response_json = $sirene->getLegalUnitBySIREN(123456789, 'dateCreationUniteLegale'); # or my $response_json = $sirene->getLegalUnitBySIREN(123456789, 'all');
When you don't specify any desired field, the module returns a selection of fields that are most likely to interest you. (see $useful_fields_legal_unit and $useful_fields_establishment in source code to find out which ones)
$useful_fields_legal_unit
$useful_fields_establishment
If you want all fields, you have to specify it explicitly by passing the value 'all' as parameter.
Each method returns a list of two elements: a return code, which is 0 in case of success, or something else in case of failure; and the result of the request (some json or an error message). In case of problem when calling API (malformed request for example), the complete sent request and the response received with headers are returned in the error message.
The module may launch a croak if the crendentials are not initialized or if the SIREN/SIRET numbers are not given in a correct format.
Some fields have more user-friendly aliases:
my $useful_fields_aliases = { nicSiege => 'nicSiegeUniteLegale', nom => [ 'denominationUniteLegale', 'nomUniteLegale' ], dateCreation => 'dateCreationUniteLegale', sigle => 'sigleUniteLegale', categorieJuridique => 'categorieJuridiqueUniteLegale', nomenclatureActivitePrincipale => 'nomenclatureActivitePrincipaleUniteLegale', activitePrincipale => 'activitePrincipaleUniteLegale', numvoie => 'numeroVoieEtablissement', typevoie => 'typeVoieEtablissement', nomvoie => 'libelleVoieEtablissement', codePostal => 'codePostalEtablissement', nomCommune => 'libelleCommuneEtablissement', adresseComplete => [ 'numeroVoieEtablissement', 'typeVoieEtablissement', 'libelleVoieEtablissement', 'codePostalEtablissement', 'libelleCommuneEtablissement' ], };
Usage:
my $response_json = $sirene->getLegalUnitBySIREN(123456789, 'nom');
is equivalent to
my $response_json = $sirene->getLegalUnitBySIREN(123456789, 'denominationUniteLegale');
Justin Fouquet <jfouquet at lncsa dot fr>
Copyright 2018-2021 by Les Nouveaux Constructeurs
This library is free software; You can redistribute it and/or modify it under the same terms as Perl itself.
To install API::INSEE::Sirene, copy and paste the appropriate command in to your terminal.
cpanm
cpanm API::INSEE::Sirene
CPAN shell
perl -MCPAN -e shell install API::INSEE::Sirene
For more information on module installation, please visit the detailed CPAN module installation guide.