# 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:
The API's default number of results for each request. You can override it with the L<< setMaxResults|https://metacpan.org/pod/API::INSEE::Sirene#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 L<< setTimeout|https://metacpan.org/pod/API::INSEE::Sirene#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_LENGHT
A SIREN number has a maximum length of 9 digits.
=head2 MAX_SIRET_LENGHT
A SIREN number has a maximum length of 14 digits.
=head2 MIN_LENGHT
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 getLegalUnitBySIREN
Search a legal unit by its SIREN number.
=head2 getEstablishmentBySIRET
Search an establishment by its SIRET number.
=head2 getEstablishmentsBySIREN
Search all the establishments attached to a legal unit identified by a SIREN number.
=head2 searchLegalUnitBySIREN
Search all legal units which SIREN number is begining by the number given in parameter.
=head2 searchEstablishmentBySIRET
Search all establishments which SIRET number is begining by the number given in parameter.
=head2 getLegalUnitsByName
Search all legal units matching the specified name. (denominationUniteLegale field)
=head2 getEstablishmentsByName
Search all establishments matching the specified name. (denominationUniteLegale field)
=head2 getLegalUnitsByUsualName
Search all legal units matching the specified name. (denominationUsuelle1UniteLegale field)
=head2 getEstablishmentsByUsualName
Search all establishments matching the specified name. (denominationUsuelle1UniteLegale field)
=head2 getCustomCriteria
You can use this method to build more specific criteria:
my $criteria1 = $sirene->getCustomCriteria('numeroVoieEtablissement', 42);
If your search is based on an historized field, you can search on all historized periods like this:
my $criteria2 = $sirene->getCustomCriteria('denominationUniteLegale', 'abc', 1);
You can choose between three search modes: 'exact', 'begin' or 'approximate' match. Default is 'approximate'.
my $criteria3 = $sirene->getCustomCriteria('libelleVoieEtablissement', 'avenue', undef, 'exact');
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 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.