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
- Updated documentation
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
- Documentation standardization
- Minor code improvements
- Errors handling improvement. The module will now display better errors
- Added checkResponse() function
- Moved getEstablishmentsByCriteria() to @EXPORT_OK
- Moved getLegalUnitBySIREN() to @EXPORT
3.501 Mon Jul 8 12:40:26 2019
- original version; created by h2xs 1.23 with options
-AX -n API::INSEE::Sirene -v 3.501
# TEST_REQUIRES => { }
# VERSION_FROM => q[lib/API/INSEE/Sirene.pm]
# clean => { FILES=>q[MANIFEST API-INSEE-Sirene-*.tar.gz debian.bak debian/libapi-insee-sirene-perl*] }
# --- MakeMaker post_initialize section:
# --- MakeMaker const_config section:
# These definitions are from config.sh (via /usr/lib/x86_64-linux-gnu/perl/5.28/Config.pm).
# They may have been overridden via Makefile.PL or on the command line.
AR = ar
CC = x86_64-linux-gnu-gcc
CCCDLFLAGS = -fPIC
CCDLFLAGS = -Wl,-E
DLEXT = so
DLSRC = dl_dlopen.xs
EXE_EXT =
FULL_AR = /usr/bin/ar
LD = x86_64-linux-gnu-gcc
LDDLFLAGS = -shared -L/usr/local/lib -fstack-protector-strong
# --- MakeMaker pm_to_blib section:
pm_to_blib : $(FIRST_MAKEFILE) $(TO_INST_PM)
$(NOECHO) $(ABSPERLRUN) -MExtUtils::Install -e 'pm_to_blib({@ARGV}, '\''$(INST_LIB)/auto'\'', q[$(PM_FILTER)], '\''$(PERM_DIR)'\'')' -- \
'lib/API/INSEE/Sirene.pm' 'blib/lib/API/INSEE/Sirene.pm'
$(NOECHO) $(TOUCH) pm_to_blib
# --- MakeMaker selfdocument section:
# here so even if top_targets is overridden, these will still be defined
# gmake will silently still work if any are .PHONY-ed but nmake won't
static ::
$(NOECHO) $(NOOP)
dynamic ::
$(NOECHO) $(NOOP)
config ::
$(NOECHO) $(NOOP)
lib/API/INSEE/Sirene.pm view on Meta::CPAN
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) = @_;
lib/API/INSEE/Sirene.pm view on Meta::CPAN
else {
$request = POST join('/', API_BASE_URL, $self->{'current_endpoint'}),
Content => [ %{ $parameters } ];
}
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) = @_;
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
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);
lib/API/INSEE/Sirene.pm view on Meta::CPAN
# 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' ],
t/API-INSEE-Sirene.t view on Meta::CPAN
my @oks_request_GET = (
[ 'getLegalUnitBySIREN', '123456789' ],
[ 'getEstablishmentBySIRET', '12345678901234' ],
);
foreach (@oks_request_GET) {
my ($method, @args) = @{$_};
can_ok($sirene, $method);
my ($err, $request) = $sirene->$method(@args);
ok(0 == $err);
$request =~ s/^Sent request:\n//m;
my $r = HTTP::Request->parse($request);
ok($r->method eq 'GET');
ok($r->uri =~ qr{/sire[nt]/\d{9,14}\?});
}
my @oks_request_POST = (
[ 'getEstablishmentsByUsualName', 'foo' ],
t/API-INSEE-Sirene.t view on Meta::CPAN
# q=((denominationUsuelle1UniteLegale%3A%22foo%22~+OR+denominationUsuelle1UniteLegale%3A*foo*))&date=2021-02-02&nombre=20
# q=((denominationUniteLegale%3A%22foo%22~+OR+denominationUniteLegale%3A*foo*))&date=2021-02-02&nombre=20
=cut
foreach (@oks_request_POST) {
my ($method, @args) = @{$_};
can_ok($sirene, $method);
my ($err, $request) = $sirene->$method(@args);
ok(0 == $err);
$request =~ s/^Sent request:\n//m;
my $r = HTTP::Request->parse($request);
ok($r->method eq 'POST');
ok($r->uri =~ qr{/siret$});
my %param = ();
foreach my $param (split '&', $r->content) {
my ($key, $value) = split '=', $param;
( run in 1.280 second using v1.01-cache-2.11-cpan-49f99fa48dc )