API-INSEE-Sirene
view release on metacpan or search on metacpan
Revision history for Perl extension API::INSEE::Sirene.
4.04
- Handle xml response when the API is down
- Fixed typing errors
4.03
- Removed unused import
- Updated README
- Updated documentation
4.02
- The getCustomCriteria method doesn't take $use_historized_field parameter anymore
The module will now auto-detect historized fields
- Added setCurrentEndpoint method
- Aliases are now mapped with more fields
- Updated documentation
4.01
- Updated dependencies in Makefile.PL
4.00
- Major internal restructuration
- The module version number is no longer depending on the INSEE's API version number
- The module is now using OOP
- The module will now send requests using POST method when possible.
This is allowed by the INSEE's API since version 3.6.0 in order to avoid too long requests in the URL.
- The API returns HTTP_NOT_FOUND code when no results have been found, even if the request was correct.
The module now handles this case correctly and returns the json body instead of dumping the request.
- In general way, the module now correctly handles the different HTTP response codes given by the API
- Better handling of tokens renewal
- Added searchLegalUnitBySIREN method
- Added searchEstablishmentBySIRET method
- Added getCustomCriteria method
- Added searchByCustomCriteria method
- Added setMaxResults method
- Added setDebugMode method
- Added setProxy method
- Added setTimeout method
- Added setCredentials method
3.507
- Updated documentation
3.506
- Fixed badly named variables
3.505
- Updated documentation
- Fixed errors in documentation from the previous version
- Fixed regression about automatic token renewal
- Fixed some return values, now all the functions return the error first and the result second
3.504
- Added automatic token renewal
- Updated documentation
3.503
- Decreased $HARD_MAX_RESULTS value from 10000 to 1000 according to the new specifications applicable from 2019-10-01
- Updated documentation
3.502
},
"name" : "API-INSEE-Sirene",
"no_index" : {
"directory" : [
"t",
"inc"
]
},
"prereqs" : {
"build" : {
"requires" : {
"ExtUtils::MakeMaker" : "0"
}
},
"configure" : {
"requires" : {
"ExtUtils::MakeMaker" : "0"
}
},
"runtime" : {
"requires" : {
"HTTP::Request::Common" : "6.18",
"HTTP::Status" : "6.18",
"JSON" : "2.9",
"LWP::UserAgent" : "6.15",
"POSIX" : "1.65",
"Switch" : "2.17",
"perl" : "5.024001"
}
}
},
---
abstract: 'An interface for the Sirene API of INSEE'
author:
- 'FOUQUET Justin <jfouquet at lncsa dot fr>'
build_requires:
ExtUtils::MakeMaker: '0'
configure_requires:
ExtUtils::MakeMaker: '0'
dynamic_config: 1
generated_by: 'ExtUtils::MakeMaker version 7.34, CPAN::Meta::Converter version 2.150010'
license: perl
meta-spec:
url: http://module-build.sourceforge.net/META-spec-v1.4.html
version: '1.4'
name: API-INSEE-Sirene
no_index:
directory:
- t
- inc
requires:
HTTP::Request::Common: '6.18'
HTTP::Status: '6.18'
JSON: '2.9'
LWP::UserAgent: '6.15'
POSIX: '1.65'
Switch: '2.17'
perl: '5.024001'
version: 4.04
x_serialization_backend: 'CPAN::Meta::YAML version 0.018'
$(DISTVNAME)
# --- MakeMaker metafile section:
metafile : create_distdir
$(NOECHO) $(ECHO) Generating META.yml
$(NOECHO) $(ECHO) '---' > META_new.yml
$(NOECHO) $(ECHO) 'abstract: '\''An interface for the Sirene API of INSEE'\''' >> META_new.yml
$(NOECHO) $(ECHO) 'author:' >> META_new.yml
$(NOECHO) $(ECHO) ' - '\''FOUQUET Justin <jfouquet at lncsa dot fr>'\''' >> META_new.yml
$(NOECHO) $(ECHO) 'build_requires:' >> META_new.yml
$(NOECHO) $(ECHO) ' ExtUtils::MakeMaker: '\''0'\''' >> META_new.yml
$(NOECHO) $(ECHO) 'configure_requires:' >> META_new.yml
$(NOECHO) $(ECHO) ' ExtUtils::MakeMaker: '\''0'\''' >> META_new.yml
$(NOECHO) $(ECHO) 'dynamic_config: 1' >> META_new.yml
$(NOECHO) $(ECHO) 'generated_by: '\''ExtUtils::MakeMaker version 7.34, CPAN::Meta::Converter version 2.150010'\''' >> META_new.yml
$(NOECHO) $(ECHO) 'license: perl' >> META_new.yml
$(NOECHO) $(ECHO) 'meta-spec:' >> META_new.yml
$(NOECHO) $(ECHO) ' url: http://module-build.sourceforge.net/META-spec-v1.4.html' >> META_new.yml
$(NOECHO) $(ECHO) ' version: '\''1.4'\''' >> META_new.yml
$(NOECHO) $(ECHO) 'name: API-INSEE-Sirene' >> META_new.yml
$(NOECHO) $(ECHO) 'no_index:' >> META_new.yml
$(NOECHO) $(ECHO) ' directory:' >> META_new.yml
$(NOECHO) $(ECHO) ' - t' >> META_new.yml
$(NOECHO) $(ECHO) ' - inc' >> META_new.yml
$(NOECHO) $(ECHO) 'requires:' >> META_new.yml
$(NOECHO) $(ECHO) ' HTTP::Request::Common: '\''6.18'\''' >> META_new.yml
$(NOECHO) $(ECHO) ' HTTP::Status: '\''6.18'\''' >> META_new.yml
$(NOECHO) $(ECHO) ' JSON: '\''2.9'\''' >> META_new.yml
$(NOECHO) $(ECHO) ' LWP::UserAgent: '\''6.15'\''' >> META_new.yml
$(NOECHO) $(ECHO) ' POSIX: '\''1.65'\''' >> META_new.yml
$(NOECHO) $(ECHO) ' Switch: '\''2.17'\''' >> META_new.yml
$(NOECHO) $(ECHO) ' perl: '\''5.024001'\''' >> META_new.yml
$(NOECHO) $(ECHO) 'version: 4.04' >> META_new.yml
$(NOECHO) $(ECHO) 'x_serialization_backend: '\''CPAN::Meta::YAML version 0.018'\''' >> META_new.yml
-$(NOECHO) $(MV) META_new.yml $(DISTVNAME)/META.yml
$(NOECHO) $(ECHO) ' },' >> META_new.json
$(NOECHO) $(ECHO) ' "name" : "API-INSEE-Sirene",' >> META_new.json
$(NOECHO) $(ECHO) ' "no_index" : {' >> META_new.json
$(NOECHO) $(ECHO) ' "directory" : [' >> META_new.json
$(NOECHO) $(ECHO) ' "t",' >> META_new.json
$(NOECHO) $(ECHO) ' "inc"' >> META_new.json
$(NOECHO) $(ECHO) ' ]' >> META_new.json
$(NOECHO) $(ECHO) ' },' >> META_new.json
$(NOECHO) $(ECHO) ' "prereqs" : {' >> META_new.json
$(NOECHO) $(ECHO) ' "build" : {' >> META_new.json
$(NOECHO) $(ECHO) ' "requires" : {' >> META_new.json
$(NOECHO) $(ECHO) ' "ExtUtils::MakeMaker" : "0"' >> META_new.json
$(NOECHO) $(ECHO) ' }' >> META_new.json
$(NOECHO) $(ECHO) ' },' >> META_new.json
$(NOECHO) $(ECHO) ' "configure" : {' >> META_new.json
$(NOECHO) $(ECHO) ' "requires" : {' >> META_new.json
$(NOECHO) $(ECHO) ' "ExtUtils::MakeMaker" : "0"' >> META_new.json
$(NOECHO) $(ECHO) ' }' >> META_new.json
$(NOECHO) $(ECHO) ' },' >> META_new.json
$(NOECHO) $(ECHO) ' "runtime" : {' >> META_new.json
$(NOECHO) $(ECHO) ' "requires" : {' >> META_new.json
$(NOECHO) $(ECHO) ' "HTTP::Request::Common" : "6.18",' >> META_new.json
$(NOECHO) $(ECHO) ' "HTTP::Status" : "6.18",' >> META_new.json
$(NOECHO) $(ECHO) ' "JSON" : "2.9",' >> META_new.json
$(NOECHO) $(ECHO) ' "LWP::UserAgent" : "6.15",' >> META_new.json
$(NOECHO) $(ECHO) ' "POSIX" : "1.65",' >> META_new.json
$(NOECHO) $(ECHO) ' "Switch" : "2.17",' >> META_new.json
$(NOECHO) $(ECHO) ' "perl" : "5.024001"' >> META_new.json
$(NOECHO) $(ECHO) ' }' >> META_new.json
$(NOECHO) $(ECHO) ' }' >> META_new.json
$(NOECHO) $(ECHO) ' },' >> META_new.json
$(NOECHO) $(NOOP)
# --- MakeMaker perldepend section:
# --- MakeMaker makefile section:
# We take a very conservative approach here, but it's worth it.
# We move Makefile to Makefile.old here to avoid gnu make looping.
$(FIRST_MAKEFILE) : Makefile.PL $(CONFIGDEP)
$(NOECHO) $(ECHO) "Makefile out-of-date with respect to $?"
$(NOECHO) $(ECHO) "Cleaning current config before rebuilding Makefile..."
-$(NOECHO) $(RM_F) $(MAKEFILE_OLD)
-$(NOECHO) $(MV) $(FIRST_MAKEFILE) $(MAKEFILE_OLD)
- $(MAKE) $(USEMAKEFILE) $(MAKEFILE_OLD) clean $(DEV_NULL)
$(PERLRUN) Makefile.PL
$(NOECHO) $(ECHO) "==> Your Makefile has been rebuilt. <=="
$(NOECHO) $(ECHO) "==> Please rerun the $(MAKE) command. <=="
$(FALSE)
To install this module type the following:
perl Makefile.PL
make
make test
make install
DEPENDENCIES
This module requires these other modules and libraries:
HTTP::Request::Common
HTTP::Status
JSON
LWP::UserAgent
POSIX
Switch
COPYRIGHT AND LICENCE
lib/API/INSEE/Sirene.pm view on Meta::CPAN
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'
],
};
sub new {
my $class = shift;
my ($credentials, $timeout, $max_results, $proxy) = @_;
my $self = bless {
credentials => $credentials,
user_agent => undef,
token_expiration => undef,
max_results => undef,
debug_mode => 0,
current_endpoint => undef,
}, $class;
$self->_initUserAgent();
$self->setProxy($proxy);
$self->setMaxResults($max_results);
$self->setTimeout($timeout);
return $self;
}
sub setCredentials {
my ($self, $credentials) = @_;
$self->{'credentials'} = $credentials;
}
sub setMaxResults {
my ($self, $max_results) = @_;
$max_results //= DEFAULT_MAX_RESULTS;
$self->{'max_results'} = $max_results > HARD_MAX_RESULTS ? HARD_MAX_RESULTS : $max_results;
}
sub setDebugMode {
my ($self, $debug_value) = @_;
$self->{'debug_mode'} = $debug_value;
}
sub setProxy {
my ($self, $proxy) = @_;
lib/API/INSEE/Sirene.pm view on Meta::CPAN
$self->{'user_agent'}->timeout($timeout);
}
sub setCurrentEndpoint {
my ($self, $endpoint) = @_;
$self->{'current_endpoint'} = $endpoint;
}
sub _dumpRequest {
my ($self, $request, $response) = @_;
my $dump = sprintf "Sent request:\n%s\n", $request->as_string;
$dump .= sprintf "Received response:\n%s\n", $response->as_string if defined $response;
return $dump;
}
sub _initUserAgent {
my $self = shift;
$self->{'user_agent'} = LWP::UserAgent->new(protocols_allowed => [ 'http', 'https' ]);
$self->{'user_agent'}->agent("Perl API::INSEE::Sirene V$VERSION");
lib/API/INSEE/Sirene.pm view on Meta::CPAN
sub _getToken {
my $self = shift;
croak 'Please provide your credentials.' if !defined $self->{'credentials'};
my $request = POST API_AUTH_URL,
Authorization => "Basic $self->{'credentials'}",
Content => [ grant_type => 'client_credentials' ];
my $response = $self->{'user_agent'}->request($request);
my $json_obj;
if ($response->content_type =~ m/^application\/json/) {
$json_obj = decode_json($response->content);
}
else {
return 1, $self->_dumpRequest($request, $response); # the API may return xml intead of json...
}
switch ($response->code) {
case HTTP_OK {
$self->{'token_expiration'} = time + $json_obj->{'expires_in'};
$self->{'user_agent'}->default_header( Authorization => "Bearer $json_obj->{'access_token'}" );
return 0;
}
case HTTP_UNAUTHORIZED { # wrong credentials
return 1 , $json_obj->{'error_description'};
}
else { # oh dear we are in trouble
return 1, $self->_dumpRequest($request, $response);
}
}
}
sub _sendRequest {
my ($self, $parameters) = @_;
my $request;
if (!exists $parameters->{'q'}) {
my @url_parameters;
lib/API/INSEE/Sirene.pm view on Meta::CPAN
if ($self->{'debug_mode'}) { # Requests will not be sent in debug mode
return 0, $self->_dumpRequest($request);
}
if (!defined $self->{'token_expiration'} || $self->{'token_expiration'} < time) {
my ($err, $msg) = $self->_getToken();
croak $msg if $err;
}
my $response = $self->{'user_agent'}->request($request);
switch ($response->code) {
case [ HTTP_OK, HTTP_NOT_FOUND ] {
return 0, $response->content;
}
case HTTP_MOVED_PERMANENTLY { # duplicated legal unit/ establishment
return 1, sprintf "%s\n%s", $response->message, $response->header('Location');
}
case [
HTTP_REQUEST_URI_TOO_LARGE, HTTP_TOO_MANY_REQUESTS,
HTTP_UNAUTHORIZED, HTTP_FORBIDDEN,
HTTP_SERVICE_UNAVAILABLE
] {
# There is no syntax error in request, the http message should be sufficient to understand the problem
return 1, $response->message;
}
else { # case HTTP_BAD_REQUEST || HTTP_INTERNAL_SERVER_ERROR
return 1, $self->_dumpRequest($request, $response);
}
}
}
sub _buildParameters {
my ($self, $usefull_fields, $desired_fields, $criteria) = @_;
# Parameters names come from the documentation
my $parameters = {
date => strftime('%Y-%m-%d', localtime),
nombre => $self->{'max_results'},
};
$parameters->{'champs'} = $self->_buildFields($usefull_fields, $desired_fields) if (defined $desired_fields && $desired_fields ne 'all');
$parameters->{'q'} = sprintf('(%s)', $criteria) if defined $criteria;
return $parameters;
}
sub _buildFields {
my ($self, $usefull_fields, $desired_fields) = @_;
lib/API/INSEE/Sirene.pm view on Meta::CPAN
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);
=head1 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:
=over 4
=item * B<Enterprise definition:>
L<< https://www.insee.fr/en/metadonnees/definition/c1496 >>
=item * B<Legal unit definition:>
lib/API/INSEE/Sirene.pm view on Meta::CPAN
=item * L<< POSIX::strftime|https://metacpan.org/pod/POSIX#strftime >>
=item * L<< Switch|https://metacpan.org/pod/Switch >>
=back
=head1 CONSTANTS
=head2 DEFAULT_MAX_RESULTS
The API's default number of results for each request. You can override it with the C<< setMaxResults >> method. A too big value may impact response time and general performances.
This constant is set to 20 results.
=head2 DEFAULT_TIMEOUT
This constant specifies how many seconds the client module has to wait for server response before giving up. You can override it with the C<< setTimeout >> method.
This constant is set to 20 seconds.
=head2 HARD_MAX_RESULTS
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 C<nombre> parameter will be forced to HARD_MAX_RESULTS value.
This constant is set to 1000 results.
=head2 MAX_SIREN_LENGTH
A SIREN number has a maximum length of 9 digits.
=head2 MAX_SIRET_LENGTH
A SIREN number has a maximum length of 14 digits.
=head2 MIN_LENGTH
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.
=head1 METHODS
=head2 getCustomCriteria
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'.
lib/API/INSEE/Sirene.pm view on Meta::CPAN
Search a legal unit by its SIREN number.
=head2 searchByCustomCriteria
This method is used to perform a search with a custom criteria built using the C<< getCustomCriteria >> method.
Before using this method, you have to specify the targeted endpoint by calling the C<< setCurrentEndpoint >> method.
my $final_criteria = "$criteria1 OR $criteria2";
my ($err, $result) = $sirene->$sirene->searchByCustomCriteria($final_criteria);
=head2 searchEstablishmentBySIRET
Search all establishments which SIRET number is begining by the number given in parameter.
=head2 searchLegalUnitBySIREN
Search all legal units which SIREN number is begining by the number given in parameter.
=head2 setCredentials
lib/API/INSEE/Sirene.pm view on Meta::CPAN
Used to specifie the reached API endpoint.
=head2 setDebugMode
Enables the debug mode. When enabled, all the requests built by the module are displayed instead of being sent.
$sirene->setDebugMode(1);
=head2 setMaxResults
Used to override the B<< DEFAULT_MAX_RESULTS >> value to get more results, within the limit of B<< HARD_MAX_RESULTS >> value.
$sirene->setMaxResults(30);
=head2 setProxy
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');
=head2 setTimeout
Used to override the B<< DEFAULT_TIMEOUT >> value.
$sirene->setTimeout(40);
=head1 PARAMETERS
All search methods take an optional C<< $desired_fields >> parameter that comes in three differents flavours:
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 C<$useful_fields_legal_unit> and C<$useful_fields_establishment> in source code to find out which ones)
If you want all fields, you have to specify it explicitly by passing the value 'all' as parameter.
=head1 RETURN VALUES
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 ...
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.
=head1 ALIAS
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'
],
};
B<Usage:>
my $response_json = $sirene->getLegalUnitBySIREN(123456789, 'nom');
is equivalent to
my $response_json = $sirene->getLegalUnitBySIREN(123456789, 'denominationUniteLegale');
=head1 AUTHOR
Justin Fouquet <jfouquet at lncsa dot fr>
=head1 COPYRIGHT AND LICENSE
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.
t/API-INSEE-Sirene.t view on Meta::CPAN
use Test::More;
use HTTP::Request;
BEGIN { use_ok('API::INSEE::Sirene') };
my $sirene = API::INSEE::Sirene->new('fake_credential');
$sirene->setCurrentEndpoint('siren');
my @oks_custom_criteria = (
# [ expected_result, field_name, value ... ],
[ '(siret:"12345678901234"~ OR siret:*12345678901234*)', 'siret', '12345678901234', ],
[ '(siret:"12345678901234"~ OR siret:*12345678901234*)', 'siret', '12345678901234', ],
[ 'periode(nomUniteLegale:"foo"~ OR nomUniteLegale:*foo*)', 'nomUniteLegale', 'foo', ],
[ 'periode(nomUniteLegale:"foo%26bar"~ OR nomUniteLegale:*foo%26bar*)', 'nomUniteLegale', 'foo&bar', ],
[ 'periode(nomUniteLegale:foo)', 'nomUniteLegale', 'foo', 'exact' ],
[ 'periode(nomUniteLegale:foo*)', 'nomUniteLegale', 'foo', 'begin' ],
[ 'libelleVoieEtablissement:foo', 'nomvoie', 'foo', 'exact' ],
[ 'periode(denominationUniteLegale:foo)', 'denominationUniteLegale', 'foo', 'exact' ],
[ 'periode(denominationUniteLegale:bar*)', 'denominationUniteLegale', 'bar', 'begin' ],
[ 'periode(denominationUniteLegale:foo%26bar)', 'denominationUniteLegale', 'foo&bar', 'exact' ],
[ 'adresseEtablissement:foo', 'adresseEtablissement', 'foo', 'exact' ],
);
foreach (@oks_custom_criteria) {
my ($expected, @args) = @{ $_ };
ok($expected eq $sirene->getCustomCriteria(@args));
}
$sirene->setDebugMode(1);
my @oks_request_GET = (
( run in 0.605 second using v1.01-cache-2.11-cpan-49f99fa48dc )