gepir
A python package for working with the Global Electronic Party Information Registry (GEPIR) SOAP API.
Requirements & Installation
- Python 3.4+ or...
- Python 2.7 and pip
To install (in a terminal or command-prompt), execute:
pip install gepir
Getting Started
To follow and execute subsequent code examples, you will need to import the following:
from gepir import GEPIR
from gepir.elements import GetKeyLicenseeResponse, GetPrefixLicenseeResponse, GetPartyByNameResponse, GEPIRParty,
PartyDataLine, GEPIRItem, ItemDataLine
To "connect" to GEPIR's API, create an instance of the GEPIR
class. Optional parameters include:
-
requester_gln (str): The 13-digit Global Location Number (GLN) of the requesting organization. This defaults to
"0000000000000" (which will work fine for making unauthenticated* requests).
-
router (str): The URI of the router end-point to which requests should be passed. This defaults to the
GS1 Global Router.
*Note: GS1 limits unauthenticated requests to 30 each day for any given IP address. See
Mitigating Request Limits for tips concerning how to make best use of these requests for common usage scenarios, and
how/where to obtain unrestricted (paid) access.
gepir = GEPIR(
requester_gln='0000000000000'
)
An instance of GEPIR
has 4 methods which will be useful to a typical user. The first three allow you to retrieve
"party" information (information about a GS1 registered entity, typically a company). The last method allows a user to
lookup item-specific information, however item information is not widely available in GEPIR at this time.
Additionally, two methods are only intended for use by a GEPIR Member Organization (MO), typically in cascading requests
to other nodes in the GEPIR network.
Requesting Company Information
The most common use for GEPIR is to lookup company ("party") information for a Global Trade Item Number (GTIN)
licensee. This can be accomplished with GEPIR.get_key_licensee()
, which accepts the following parameters:
-
requested_key_code (str): This key code indicates the type of data contained in the requested_key_value.
- "GTIN": A 14-digit Global Trade Item Number (GTIN), composed of numneric digits only.
- "GLN": A 13-digit Global Location Number (GLN), composed of numeric digits only.
- "SSCC": An 18-digit Serial Shipping Container Code (SSCC), composed of numeric digits only.
- "GRAI": A 13-digit Global Returnable Asset Identifier (GRAI), composed of numeric digits only.
- "GIAI": A 30-digit Global Individual Asset Identifier (GIAI), composed of numeric digits only.
- "GSRN": An 18-digit Global Service Relation Number (GSRN), composed of numeric digits only.
- "GDTI": A 13-digit Global Document Type Identifier (GDTI), composed of numeric digits only.
- "GSIN": A 17-digit Global Shipment Identification Number (GSIN), composed of numeric digits only.
- "GINC": A 30-digit Global Identification Number for Consignment (GINC), composed of numeric digits
only.
- "GCN": A 13-digit Global Coupon Number (GCN), composed of numeric digits only.
-
requested_key_value (str): A value corresponding to the indicated requested_key_code.
-
requested_language (str): A 2-3 digit language code (ISO 639), optionally followed by
a hyphen and region code (ISO 15924).
-
get_key_licensee (Sequence[`GEPIRRequestedKey`_]): If more than one set of the preceding parameters need to be
incorporated into the same request, a series of `GEPIRRequestedKey`_ instances can be passed instead of,
or in addition to, the previous 3 parameters.
The following parameters for GEPIR.get_key_licensee()
are only intended for use by a GEPIR MO:
-
on_behalf_of_gln (str): The GLN of the originator of the request. This remains unchanged if the request
is cascaded to another server. This should only be populated by the initiating MO. This must be
a valid, active GLN. To prevent spoofing, if the GEPIR Premium authentication fails on
requester_gln
+ IP
address, this field should be set to None
. Furthermore, even if the requester passes authentication,
only known GEPIR nodes should be allowed to set this field.
-
is_authenticated (bool): State of the incoming requester as to whether the user is a member in good
standing or not. This should only be populated by the initiating MO (it is no longer assumed when a
request comes from an initiating trusted router). To prevent spoofing, if the GEPIR Premium authentication
fails on
requester_gln
+ IP address, this field should be set to None
. Furthermore, even if the
requester passes authentication, only known GEPIR nodes should be allowed to set this field.
-
cascade (int): An integer between 0 and 9 indicating the number of times a request may be cascaded to
another server. This element is decremented each time the request is passed on. A request with a cascade
count of
0
must not be cascaded further.
GEPIR.get_key_licensee()
will return an instance of GetKeyLicenseeResponse, a container element for a sequence of
GEPIRParty instances.
gklr = gepir.get_key_licensee(
requested_key_code='GTIN',
requested_key_value='00037447250897'
) # type: GetKeyLicenseeResponse
for gepir_party in gklr.gepir_party: # type: GEPIRParty
print(gepir_party)
This method can also be used to retrieve party information for additional GS1 keys, such as a
Global Location Number (GLN) licensee.
gklr = gepir.get_key_licensee(
requested_key_code='GLN',
requested_key_value='0037447121067'
) # type: GetKeyLicenseeResponse
for gepir_party in gklr.gepir_party: # type: GEPIRParty
print(gepir_party)
GEPIR.get_prefix_licensee()
is similar to GEPIR.get_key_licensee()
(and accepts the same arguments), but it
only returns a GEPIR party if that party licenses the Global Company Prefix (GCP) corresponding to the key requested
(as opposed to licensing only the solitary key).
gplr = gepir.get_prefix_licensee(
requested_key_code='GTIN',
requested_key_value='00037447250897'
) # type: GetPrefixLicenseeResponse
for gepir_party in gplr.gepir_party: # type: GEPIRParty
print(gepir_party)
You will likely find the above method to be redundant, because it is possible to determine whether a GEPIRParty
licenses the prefix, or only an individual GS1 key, by the presence or absence of a `gs1_company_prefix_licensee`_.
for gtin in ('00037447250897',):
gklr = gepir.get_key_licensee(
requested_key_code='GTIN',
requested_key_value=gtin
) # type: GetKeyLicenseeResponse
for gepir_party in gklr.gepir_party: # type: GEPIRParty
for party_data_line in gepir_party.party_data_line: # type: PartyDataLine
if party_data_line.gs1_company_prefix_licensee is None:
print("This party is not the licensee of this key's GCP.")
else:
print(
"This party *is* the licensee of this key's GCP: \n" +
str(party_data_line.gs1_company_prefix_licensee)
)
Lastly, information about a party can be retrieved based on a country and all or part of the company's name and
(optionally) additional locale information about the company, using GEPIR.get_party_by_name()
, which accepts the
following parameters:
-
requested_country (str): A 2-digit country code (ISO 3166-1 alpha-2) indicating which country to search. By
default, the code "ZZ" is used, which initiaes a worldwide search. A worldwide search takes significantly longer,
however—so it is recommended that a country code be provided, when known.
-
requested_party_name (str): All or part of the name of a party.
-
requested_street_address (str): Find parties with this text in the address.
-
requested_city (str): Find parties within this city.
-
requested_postal_code (str): Find parties within this postal code.
-
requested_language (str): (A 2-digit or 3-digit language code) Specifies the language of the request
text-fields if the language is not the default language of the information provider.
The following parameters for GEPIR.get_party_by_name()
are only intended for use by a GEPIR MO:
-
on_behalf_of_gln (str): The GLN of the originator of the request. This remains unchanged if the request
is cascaded to another server. This should only be populated by the initiating MO. This must be a valid,
active GLN. To prevent spoofing, if the GEPIR Premium authentication fails on
requester_gln
+ IP
address, this field should be set to None
. Furthermore, even if the requester passes authentication,
only known GEPIR nodes should be allowed to set this field.
-
is_authenticated (bool): State of the incoming requester as to whether the user is a member in good
standing or not. This should only be populated by the initiating MO (it is no longer assumed when a
request comes from an initiating trusted router). To prevent spoofing, if the GEPIR Premium authentication
fails on
requester_gln
+ IP address, this field should be set to None
. Furthermore, even if the
requester passes authentication, only known GEPIR nodes should be allowed to set this field.
-
cascade (int): An integer between 0 and 9 indicating the number of times a request may be cascaded to
another server. This element is decremented each time the request is passed on. A request with a cascade
count of
0
must not be cascaded further.
for country, company, city in (
('US', 'Leatherman', 'Portland'),
):
gpbnr = gepir.get_party_by_name(
country,
company,
requested_city=city
) # type: GetPartyByNameResponse
for gepir_party in gpbnr.gepir_party: # type: GEPIRParty
print(gepir_party)
Requesting Item Information
Item information is not widely available in GEPIR at this time, however it can be queried using
GEPIR.get_item_by_gtin()
, which accepts the following parameters:
-
requested_gtin (str): A 14 digit global trade item number.
-
requested_language (str): (A 2-digit or 3-digit language code) Specifies the language of the request
text-fields if the language is not the default language of the information provider.
The following parameters for GEPIR.get_item_by_gtin()
are only intended for use by a GEPIR MO:
-
on_behalf_of_gln (str): The GLN of the originator of the request. This remains unchanged if the request
is cascaded to another server. This should only be populated by the initiating MO. This must be a valid,
active GLN. To prevent spoofing, if the GEPIR Premium authentication fails on
requester_gln
+ IP
address, this field should be set to None
. Furthermore, even if the requester passes authentication,
only known GEPIR nodes should be allowed to set this field.
-
is_authenticated (bool): State of the incoming requestor as to whether the user is a member in good
standing or not. This should only be populated by the initiating MO (it is no longer assumed when a
request comes from an initiating trusted router). To prevent spoofing, if the GEPIR Premium authentication
fails on
requester_gln
+ IP address, this field should be set to None
. Furthermore, even if the
requester passes authentication, only known GEPIR nodes should be allowed to set this field.
-
cascade (int): An integer between 0 and 9 indicating the number of times a request may be cascaded to
another server. This element is decremented each time the request is passed on. A request with a cascade
count of
0
must not be cascaded further.
gibgr = gepir.get_item_by_gtin(
requested_gtin='04760000100013'
) # type: GetItemByGTINResponse
for gepir_item in gibgr.gepir_item: # type: GEPIRItem
for item_data_line in gepir_item.item_data_line: # type: ItemDataLine
print(item_data_line)
Interpreting a GEPIR Response
The following classes, representing elements from which a GEPIR response is composed, can be found in the module
gepir.elements
.
Class |
Properties (types) |
GetKeyLicenseeResponse |
-
gepir_party (Sequence[GEPIRParty]): A sequence of objects containing
information about a GEPIR party. Each GEPIRParty represents one party (company).
|
GetPrefixLicenseeResponse |
-
gepir_party (Sequence[GEPIRParty]): A sequence of objects containing
information about a GEPIR party. Each GEPIRParty represents one trade item.
|
GetPartyByNameResponse |
-
gepir_party (Sequence[GEPIRParty]): A sequence of objects containing
information about a GEPIR party. Each GEPIRParty represents one party (company).
|
GetItemByGTINResponse |
-
gepir_party (Sequence[`GEPIRItem`_]): A sequence of objects containing
information about a trade item. Each `GEPIRItem`_ represents one trade item.
|
GEPIRParty |
-
party_data_line (Sequence[PartyDataLine]): A sequence of objects containing
information about a party (company). Each data line represents the party information
available for this request from one node in the GEPIR network (one MO).
|
PartyDataLine |
-
last_change_date (datetime): A date assigned by the system indicating the last
time this information was altered.
-
gs1_company_prefix (str): The GS1 Company Prefix of the GS1 key being requested.
-
information_provider (`GEPIRPartyInformation`_): Party information about the
originator of this response line.
-
party_data_language (str): Indicates the language used to represent data in this
response line.
-
return_code (GEPIRReturnCode): Indicates the success or failure of a request.
-
address (`Address`_): A location at which representatives of this party may be
reached.
-
gepir_requested_key (`GEPIRRequestedKey`_): Details about the requested GS1 key.
This can be useful when multiple keys are queried in the same request.
-
gepir_item_external_file_link (Sequence[`ExternalFileLink`_]): One or more
references to related electronic files.
-
responder_specific_data (`ResponderSpecificData`_): A user-defined field for
passing additional information about this party.
-
gs1_company_prefix_licensee (`GEPIRPartyInformation`_): Information about the
party licensing the prefix contained in the referenced GS1 key. This will be absent
when a solitary key has been licensed (a very uncommon scenario), as opposed to a
prefix.
-
gs1_key_licensee (`GEPIRPartyInformation`_): Information about the party licensing
the referenced GS1 key.
-
information_provider (`GEPIRPartyInformation`_): Information about the party from
whom this response line originates.
-
contact (Sequence[`Contact`_]): Information about a individuals or departments
acting as a contact for this organization.
|
GEPIRReturnCode |
-
text (str): "0" indicates success, all other values indicate an error has
occurred.
- "0" (Query Successful): The request has been successfully completed and the response
is in the body of the message.
- "1" (Missing or invalid parameters): One or more parameters are missing or
incorrect. This might be and incorrect length, invalid check digit, a non-numeric
characters in a number, etc. No data is returned.
- "2" (PhoneBookRecord not found): No record exists for this key or these search parameters. No
data is returned.
- "3" (No exact match on Requested Key): No record was found for this Requested Key.
The data held in the MO database for this company prefix is returned.
- "4" (Too many hits): Over twenty records match the search criteria. Only twenty are
returned.
- "5" (Unknown GS1 Prefix): The GS1 prefix (3 digit country code) does not exist.
- "6" (Response may be incomplete): One or more servers failed to respond for the
global search (“ZZ”). Such data as is available is returned.
- "7" (Request timed out): There was a timeout somewhere in the server chain. No data
is returned.
- "8" (No catalogue exists): A request has been made for GTIN information, but there
is no server for this company. No data is returned.
- "9" (Company information withheld): The company prefix in the request exists, but
the company has not released its information for publication. The name and address
of the responsible MO is returned.
- "10" (Prefix no longer subscribed): The company prefix in the request exists, but
the company is no longer a member of GS1 under this prefix. The name and address of
the responsible MO is returned.
- "11" (Country not on the GEPIR network): There is no GEPIR MO server for this
country. This should only be used with Get Party by Name.
- "12" (Item information withheld): The GTIN in the request exists, but the company
has not released its information for publication.
- "13" (Unauthorised number): The company prefix in the request is known to be
unauthorised. The name and address of the responsible MO is returned.
- "14" (Daily request limit exceeded): The user has exceeded the number of "free"
requests permitted (30) and the request is rejected. No data is returned. The
responder_Gln element is set by the node refusing the request.
- "15" (GLN not assigned): The provided GS1 Key is valid, however a GLN not assigned
to this key.
- "16" (Internal use only): Prefixes 020-029 and 040-049 are for a company's internal
use only, so no information can be returned. Returns only the name and address of
the MO which was queried.
- "17" (Internal use only): Prefixes 200-299 are for a company's internal use only, so
no information can be returned. Returns only the name and address of the MO which
was queried.
- "18" (ISSN): Prefix 977 is used for serial publications (ISSN), so no information
can be returned. Only the name and address of the MO queried is returned.
- "19" (ISBN): Prefixes 978-979 are for books (ISBN), so no information can be
returned. Returns only the name and address of the MO which was queried.
- "20" (Coupon Prefix): Prefixes 050-059 are for coupons, so no information
can be returned. Returns only the name and address of the MO which was queried.
- "21" (Prefix never allocated): No record exists for this key, so not data can be
returned. This code can only be used when historical data is available.
- "97" (Unsupported request for this version): The request contains elements which
cannot be processed by a GEPIR Router of the current version.
- "98" (Authorization failed): The Authorization process has failed and access is not
granted.
- "99" (Server error): The router is functional, however accessjng data is not
currently possible. The
responder_gln is set by the node detecting the error.
-
code_list_version (str): Which snapshot of the code-list was this code taken
from?
|
Mitigating Request Limits
References