GS1 US Data Hub®

View/Use API
Developer Portal User Guide

Version 5.5
Date: July 25,
2022
Table of Contents

3
API Tools (OpenAPI, Odata)…..………………………………………………..
GS1 US APIs……………………………………………….……........................ 4
GS1 US Data Hub Developer Portal Home Page ……........................ 6
Profile Screen…............................................................................... 7
API Screen…….……………………………………………………………………… 9
API “Try It” and Search Functionality ............................................ 10
“Try It” for Product…………….......................................................... 11
Request Filters for Product API ……………...................................... 12
Usage Analytics………………………………………………........................... 13
Usage Filters ………………………………………………………………………….. 14
Health Filters …………………………………………………………………………. 15
Activity Summary ...........................................................……………. 16
Browser Considerations…………………….. ...............................……… 17
Appendix A – Sample Product API Results ............................……… 18
Appendix B – Sample Location API Results ................................…… 20
Appendix C – Sample Company API Results ................................… 21
Appendix D – Error Messages ………………………………………………….. 22

Glossary of Terms ................................................................... 23

Data Hub Developer Developer's Portal User Guide 2

API Tools

GS1 US APIs operate under the OpenAPI (or Odata) standards. Information and
tools associated with these platforms can be accessed directly from the managing
organizations as outlined below.

OpenAPI Information and Tools

The OpenAPI Specification is a community-driven open specification within the
OpenAPI Initiative, a Linux Foundation Collaborative Project. OpenAPI documents
describe an API's services and are represented in either YAML or JSON formats.
These documents may either be produced and served statically or be generated
dynamically from an application.

A list of known tools that implement the 3.0.0 specification of OpenAPI can
be found at the URL below:

https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md

A list of issues, presented as a Users Forum, with the current specification of

OpenAPI can be found at the URL below. This is an excellent resource for developers
in identifying and addressing problems that they may have with the structure and
behavior of their API(s). Note that this site also contains general notifications about
meetings and activities of the community:

https://github.com/OAI/OpenAPI-Specification/issues

OData Information and Tools

OData is an ISO/IEC approved, OASIS standard that defines a set of best practices for
building and consuming RESTful APIs.

A set of code libraries for OData can be found at the URL below:

https://www.odata.org/libraries/

A list of issues, presented as a Users Forum, with the current specification of

OpenAPI can be found at the URL below. This is an excellent resource for developers
in identifying and addressing problems that they may have with the structure and
behavior of their API(s). Note that this site also contains general notifications about
meetings and activities of the community:

Data Hub Developer Developer's Portal User Guide 3

GS1 US APIs

Product
GS1 US Product API is based on the OpenAPI standard. GS1 US is currently
supporting 2 versions of this API, with V.4 being maintained in support of legacy API
users. The Product API is a search API and is currently restricted to Data Hub
View/Use subscriptions.

Product Search of the GS1 Registry Platform (new)

A new capability is being added to the GS1 US Product View/Use API in Release 5.0.
Specifically, subscribers will now be able to run GTIN searches to the global GS1 Registry
Platform through a separate end-point from their Data Hub searches. The Request URL
(end-point) can be found on the Product API page of the Data Hub Developers Portal by
selecting the “Get GTIN from GRP” option.

Location
GS1 US Location APIs are based on the OData standard. GS1 US currently supports
a search API for Data Hub View/Use subscriptions (Location-API) and a
Create/Modify API for GLN Managers (MyLocation-API).

Company
GS1 US Company API is based on the OData standard. GS1 US is currently
supporting 2 versions of this API, with V.2 being maintained in support of legacy API
users. The Company API is a search API and is restricted to Data Hub View/Use
subscriptions.

Data Hub Developer Developer's Portal User Guide 4

 Details on the search terms available for filtering searches on GS1 US APIs can be
identified by reviewing the API result examples shown in Appendix A, Appendix B,
and Appendix C of this guide.

Data Hub Developer Developer's Portal User Guide 5

GS1 US Data Hub Developer Portal Home Page
Home Page Overview

GS1 US Data Hub Developer Portal operates under the Azure API Management
capabilities. The Developer Portal provides you with a way to test your APIs,
check usage, and manage your subscriptions.

3
2

1 Click the hyperlinked titles to display the pages in the Developer's Portal.
Alternatively, you can click the ‘APIs’ option in the menu, as described in step 1.

2 Use the menu to navigate within the Developer's Portal.

3 Click the down arrow on your company’s account number for a profile of the
subscription details and their status. This information includes the API Keys
associated with your account
4 Contact GS1 US if you need support:
For API Administration: direct your questions to [email protected]
For API Technical Questions: direct your questions to the
[email protected] mailbox

Data Hub Developer Developer's Portal User Guide 6

Profile Screen
The Profile screen provides information specific to your account and subscription details
by GS1 US Data Hub subscription (Product, Company, Location, My Location) and
status (Active, Inactive). This page allows you to customize the name of your API
subscription, as well as display or regenerate primary and secondary keys.

3 4

Username | GS1 US Account Number: the organization name and

1 account number of the subscription holder. Click on the down arrow to
reveal the Profile screen.

2 Email and Organization Name: email address for the member who is
currently signed in account (organization) name

My Subscriptions: this section provides a summary of your

3 subscriptions, allows for customization (Rename) of your subscription,
enables you to display (show) or regenerate your API keys and shows the
status of each subscription.

4 Analytics Reports: Click here to view the usage analytics of your API
calls (see example on following page).

Data Hub Developer Developer's Portal User Guide 7

Profile Screen

1
1 Usage/Health:
Graphic provides
overall usage
statistics for company
APIs

Top Product:
2 Top Subscription:
Top APIs:
Top Operations:
email address for the
Tabular Statistics
filtered and ordered
by specific
subscriptions

Data Hub Developer Developer's Portal User Guide 8

API Screen
On the API screen, you can view a listing of your currently defined
applications, categorized by Company, Location, MyLocation and Product.

Click a version to hyperlink to the detail screen.

Each application has an access application identifier and an access

application key.

Three versions of Data Hub API are currently supported.

Version 2 (v2) uses the RESTful endpoint structure and exchanges data in
JSON format using standard HTTP verbs (GET, PUT, POST, DELETE). Version
2 of the API also supports a subset of the features within the Odata
specification including filtering and paging capabilities. V2 will be sunset
at the end of 2019.

Version 3 (v3) also uses the same endpoint structure and exchanges data
in multiple formats (JSON, CURL, C++, Java, JavaScript, ObjC, PHP, Python
and Ruby). Version 3 added modified date and range of date search
capabilities not available with v2.

Version 4 (v4) is available for Products and includes OpenAPI (formerly

Swagger Specification). OpenAPI versions for Location and Company are
planned for future releases.

Data Hub Developer Developer's Portal User Guide 9

API “Try It” and Search Functionality

Before you invest in building your API, use the “Try It” feature on any API
calls. With Try It, you can send an HTTP request interactively using the API
Reference and immediately see the returned HTTP Response on the
Developer Portal screen. The following pages provide highlights of each call.

Searches using the API may be performed using ODATA. Screen shots of
OpenAPI searches are included at the end of this document. More
information regarding the Odata specifications can be found
at www.odata.org

Data Hub Developer Developer's Portal User Guide 10

“Try It” for Product
Follow the steps below for all of the API References.

1 Click the GET button to get a single product or expand the request
url, parameters, headers, etc. This example displays the request
parameters for a multiple product search. Input parameters are
case sensitive

2 Click the “Try IT” button to test your search sample using OpenAPI.

3 Enter a shared GTIN to search

APIKey is required. Your primary and secondary key are located on

your Profile screen.

Data Hub Developer Developer's Portal User Guide 11

Request Filters for Product API
Follow the steps below for all of the API References.

1
2

1 Clicking the GET button will return expand the request url,
parameters, headers, etc.

This example displays the request parameters for a multiple

2 product search. Filter parameters are case sensitive

Exact input values as well as explanations of each Request

3 Parameter can be found as below.

Data Hub Developer Developer's Portal User Guide 12

Usage Analytics
With Usage Analytics you will be able to measure utilization, or in other words,
the number of times your application interacts with the Data Hub API.

The At a Glance screen allows you to view up to 90 days of activity.

Select the desired time frame: Today, Yesterday, Last 7 Days, Last 30
1 Days or Last 90 Days.

2 Usage / Health results will be summarized graphically for Calls, Response

Time, Bandwidth and Errors.

Below the Usage / Health chart, are summaries of Successful, Blocked and
Failed Calls, Other calls, Total calls, Average Response Time and
Bandwidth for each of these categories:
• Top Products
• Top Subscriptions
• Top APIs
• Top Operations

Data Hub Developer Developer's Portal User Guide 13

Usage Filters

The Usage tab allows you to filter by date range, API type (product) and the
operation (Get, Post).

5
4

Select Time Period and/or date range

1
Identify the subscription type (Product) using drop down menus and zero
2 in on the specific operation of the API.

View Calls. This counts the number of times your application has sent a
3 request to the Data Hub API. In the example above the application
initiated a single request on February 1 between 6 and 9 am .

View Bandwidth. Hovering over the Calls graphic will also display
4 bandwidth results for that day/time.

This is a geographic representation where the API originated.

5

Data Hub Developer Developer's Portal User Guide 14

Health Filters
The Health filter allow you to further capture results of status codes, cache,
API and service response times. Hover over any date to view values
displayed graphically.

Data Hub Developer Developer's Portal User Guide 15

Activity Summary
The Activity tab provides columnar summary views based on your selection
criteria: by timeframe, date range, subscription type and operation.

1 Select Time Period and/or date range

2 Identify the subscription type (1) All Products, (2) All APIs, and (3)
All operations; by using drop down menus to focus on the specific
operation of the API.

3 Review the summary tables provided below the filter for APIs, call
requests (APIs and Operations) and Subscription Types (Products
and Subscriptions)

Data Hub Developer Developer's Portal User Guide 16

Browser Considerations

Warnings/Issues (Chrome Browser)

There is a known limitation within the Google Chrome browser for searches beyond
a 1000 record limit. This issue will result in a page freeze for Data Hub API users
who run their searches through the Developers Portal and who are using the
Chrome browser.

The issue does not restrict any API searches performed outside of the platform and
is a browser restriction (not a Data Hub platform restriction). API searches of
greater than 1000 records operate properly within the Developer’s Portal for all
other Browsers (note that IE is not supported by Data Hub).

The browser limitation results in the frozen state pictured below.

Data Hub Developer Developer's Portal User Guide 17

 Appendix A: Sample Product API Search Results
{
"product": {
"Id": 20275799,
"CompanyName": "ALL 4 U LLC",
"CompanyURI":
"/company/v3/company/GLN/0192408000000",
"Prefix": "0192408",
"GTIN": "00192408145701",
"GTIN13": "",
"GTIN12": "192408145701",
"PackagingLevel": "Each",
"Industry": "General",
"EntityGLN": "0192408000000",
"ProductDescription": "USS Widgeon ASR-1
License Plate Frame",
"ProductDescriptionLanguage1": "en",
"ProductDescription2": "",
"ProductDescriptionLanguage2": "",
"SKU": "LSFASR-1",
"BrandName": "MilitaryBest",
"BrandNameLanguage1": "en",
"BrandName2": "",
"BrandNameLanguage2": "",
"Status": "In Use",
"IsVariable": false,
"IsPurchasable": false,
"Dimensions": {
"Height": null,
"Width": null,
"Depth": null,
"DimensionMeasure": ""
},
"Weight": {
"GrossWeight": null,
"NetWeight": null,
"WeightMeasure": ""
},
"Comments": null,
"TargetMarket": [],
"ChildGTINs": null,
"Quantity": null,
"SubBrandName": "",
"ProductDescriptionShort": "",
"LabelDescription": "",

Data Hub Developer Developer's Portal User Guide 18

 Appendix A: Sample Product API Search Results (cont)

"NetPackageContent": {
"NetContent1Count": "",
"NetContent1UnitOfMeasure": "",
"NetContent2Count": "",
"NetContent2UnitOfMeasure": "",
"NetContent3Count": "",
"NetContent3UnitOfMeasure": ""
},
"GlobalProductClassification": "",
"ImageURL": "",
"Ancestors": [],
"Descendants": [],
"IsEnhanced": "",
"ModifiedDate": "2017-10-
10T21:07:24.5700000Z"
},
"messages": [],
"responseCode": "VB0001",
"responseMessage": "Product lookup is
successful"
}

Data Hub Developer Developer's Portal User Guide 19

 Appendix B: Sample Location API Search Results

Pragma: no-cache
Cache-Control: no-cache
Date: Tue, 08 Oct 2019 17:28:29 GMT
Set-Cookie:
ApplicationGatewayAffinity=9e2f486c7acfd5cf59a5
616f300d9b6cf221101dd76920dd0124009a562c25d8;Pa
th=/;Domain=internaldh.stage.gs1us.org
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Content-Length: 735
Content-Type: application/json; charset=utf-8
Expires: -1

{
"name": "Johnson & Johnson - HCS",
"name2": "",
"gln": "0705038000007",
"parentGln": null,
"replacedGln": null,
"status": "Active",
"prefix": null,
"industry": "Healthcare",
"roleInSupplyChain": "Supplier",
"address": {
"addressLine1": "425 HOES LN",
"addressLine2": "",
"addressLine3": "",
"city": "PISCATAWAY",
"state": "NJ",
"zip": "08854-4103",
"country": "US",
"phone": "732-562-3293",
"dateUspsVerified": "2016-02-03T00:00:00",
"bypassAddressVerification": false
},
"locationTypes": ["Bill To", "Org Entity"],
"conditionalAttributes": [{
"attributeName": "Business Sector",
"attributeValue": "Health Care - Medical
Devices"
}],
"GDSNGLNLocationTypes": [],
"createDate": "2010-08-10T10:53:47",
"updateDate": "2010-08-10T10:53:47",
"reValidationDate": null,
"GPO": null,
"selfManaged": false
}

Data Hub Developer Developer's Portal User Guide 20

 Appendix C: Sample Company API Search Results

Pragma: no-cache
Cache-Control: no-cache
Date: Tue, 08 Oct 2019 17:38:04 GMT
Set-Cookie:
ApplicationGatewayAffinity=af5c790b2bd506af5f5d
e3350dad737f2bfadd050d015ae06b2a4963c1e8c943;Pa
th=/;Domain=internaldh.stage.gs1us.org
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Content-Length: 439
Content-Type: application/json; charset=utf-8
Expires: -1

[{
"Source": "GS1 US, INC.",
"EntityGLN": "0705038000007",
"CompanyName": "Johnson & Johnson Health Care
Systems, Inc.",
"StreetAddress1": "PO BOX 6800",
"StreetAddress2": "",
"StreetAddress3": "",
"City": "PISCATAWAY",
"StateProvince": "NJ",
"ZipCode": "08855-6800",
"Country": "USA",
"GSRN": "101234500011954334",
"ModifiedDate": "2014-10-18",
"Prefixes": {
"UPCPrefix": "705038",
"GS1Prefix": "0705038",
"PrefixStatus": "Active",
"ModifiedDate": "2014-10-18T00:00:00"
}
}]

Data Hub Developer Developer's Portal User Guide 21

 Appendix D: Error Messages

GS1 US error messaging for API services generally follow REST HTTP Status
Code standards using the below table.

HTTP Status Code Description

200 OK Successful.

201 Created Created.

400 Bad Request Bad input parameter. Error message should indicate
which one and why.

401 Unauthorized The client passed in the invalid Auth token. Client
should refresh the token and then try again.

403 Forbidden Customer doesn’t exist. Application not registered.

Application try to access to properties not belong to
an App.

404 Not Found Resource not found.

405 Method Not Allowed The resource doesn't support the specified HTTP
verb.

409 Conflict Conflict.

412 Precondition Failed Precondition failed.

500 Internal Server Error Servers are not working as expected. The request is
probably valid but needs to be requested again later.

503 Service Unavailable Service Unavailable.

Data Hub Developer Developer's Portal User Guide 22

Glossary of Terms

Business Terms

BrandName: Indicates the name of the product line used with consumers

Entity GLN: A GLN that uniquely identifies a company that has a business
relationship with GS1 US or another GS1 Member Organization. A single entity GLN
can be associated with other GLNs or with one or more GS1 Company Prefixes.

GLN: Global Location Numbers are used to identify parties to business transactions;
functional groups within a company; or real, physical “places” that might ship,
receive, process, or hold inventories.

GS1 Company Prefix: The GS1 Company Prefix is at the heart of the GS1 system
of identifiers. It forms the base for a family of identifiers that are globally unique
and can be used for a host of different applications. GS1 assigns GS1 Company
Prefixes to entities that administer the allocation of GS1 System identification
numbers. GS1 Company Prefixes are between 7 and 11 digits in length. The GS1
Company Prefix is located on your prefix certificate, and it begins with a zero “0.”

GTIN: Global Trade Item Numbers uniquely identify trade items at all item and
package levels, ensuring that they are always identified correctly anywhere in the
world. Each trade item that is different from another is allocated a separate, unique
GTIN. GTINs are encountered most frequently at retail point of sale and on inner
packs, cases, and pallets of products in a distribution/warehouse environment. They
are commonly used on purchase orders and in delivery and payment documents.

SKU: (Stock Keeping Unit) Internal company identifier

Target Market: Designated market of sale for the product

U.P.C. Company Prefix: A special representation of a GS1 Company Prefix, it is

only used to create GTIN-12, Coupon-12, RCN-12, and VMN-12, which are encoded
in a UPC-A Bar Code. This prefix is used specifically for creating a GTIN-12 for
items that cross the point of sale. U.P.C. Company Prefixes are between 6 and 10
digits in length.

Data Hub Developer Developer's Portal User Guide 23

Glossary of Terms (continued)

Technical Terms

AI: Application Identifier. AIs identify the meaning and format of data within a
barcode.

API: Application Programming Interface. The API provided by GS1 US in the form
of a web service exposing GS1 US certified data to licensed parties. GS1 US is the
API provider. The licensed parties are the API consumers. API consumers create
the end user product or service that retrieves GS1 US certified data in real-time,
seamlessly integrated into licensed parties’ business applications.

APIM: API Management. Tools to help publish APIs to external, partner, and
employee developers securely and at scale.

EAN: International Article Number, European Article Number. Barcode encoding

13 digit number for retail point-of-sale.

EDI: Electronic Data Interchange. EDI enables the computer-to-computer exchange

of business documents between companies using a standardized format.

GDSN: Global Data Synchronization Network. An Internet-based, interconnected

network of interoperable data pools and the GS1 Global Registry® that enables
companies to exchange standardized and synchronized supply chain data and
accurate product information

GRP: GS1 Registry Platform. A "primary node" of authoritative data about all
GS1 identifiers on the web.

JSON: JavaScript Object Notation. JSON is the Internet media type returned by the
API provider within the HTTP response.

REST: Representational State Transfer: This has emerged as a predominant web

API design model.

Data Hub Developer Developer's Portal User Guide 24