An API is used to exchange information between applications. Not long ago, information was exchanged from user to user. An archive with data files from Application A was exported and sent to the user's email. The user had to download the files and upload them to Application B. Unfortunately, this way of exchanging data caused users a lot of problems. For example, users had to wait for the archive with the data to be sent or the file structure may have been changed without notice and Application B may not support the new file structure. However, business can’t wait and problems had to be manually corrected by the user to access the data they need.
APIs were designed to solve these problems by connecting an application or tool to an external application (the API). The format of their dialogue is predetermined and they communicate as if they have known each other for a very long time.
What Benefits Will I Gain from Using gap intelligence's API?
Spoiler: It's an easy and convenient way to access to millions of 4Ps records at any time. The gap intelligence API even works on the holidays!
To put it simply: your favorite tool + gap intelligence data on demand = 2 x Success. The gap intelligence API is a unique product in the market research industry. Every week, the gap intelligence database is updated with millions of data points for the various categories that gap tracks. Each 4P product change is recorded in detail in the database, and further allows both gap intelligence analysts and our customers to use this data for market analysis. With the gap intelligence API, the data is available to you on demand. Every bit of information that gap intelligence collects and stores is shared with you. From this point on, there are no boundaries when using your favorite tool and combining it with your favorite gap intelligence data.
Getting Started with gap intelligence API
The gap intelligence API exposes a JSON REST interface and uses the OAuth 2.0 protocol for authentication and authorization.
Before you start, you must have a client_id and client_secret provided by gap intelligence. Think of the client_id and client_secret like the login and password for your email account. Contact a representative of gap intelligence to request your credentials.
When you login to your email account, you enter your credentials once, a session is created and you can read your mail without re-entering your account credentials every time. In the API world, sessions are arranged differently. After you have submitted client_id and client_secret and the server has identified customer, you are given a unique access_token for a limited time to use.
curl -X "POST" "https://api.gapintelligence.com/oauth/token"
-H 'Content-Type: application/json; charset=utf-8'
-d $'{
"client_id": "***** Hidden Client ID *****",
"client_secret": "***** Hidden Client Secret *****",
"grant_type": "client_credentials"
}'
Each following API request must contain the access token.
gap intelligence API Resources
The set of gap intelligence API endpoints available to you is determined by on your company’s subscription level. For more information, contact a gap intelligence representative.
Requests to the gap intelligence API should use the HTTPS protocol. A simple request for information requires the use of the GET method. In case of an error, the response status will be in the 400 range, and the response body contains an error message. All responses with status 500 indicates that there is a problem on the server side, and gap intelligence is already working on it. If you continue to receive the same error, please contact a representative of gap intelligence so we can assist you.
An API response may contain meta data that contains additional information. For example, it may contain pagination information with the number of total records, the number of pages and the numbers of the next and previous pages.
For authorized access to a resource, each request must contain an authorization header with an active access token. If the token is invalid, the API will return a respone status code of 401 Unauthorized.
Parameters, used for things like filtering the data, can be passed as query attributes at the end of the URL, starting with ?. It is possible to pass several parameters separated by the &. The set of accepted parameters differs depending on the resource endpoint and your subscription.
Lets consider the basic features of the API using Pricing Endpoint.
Filtering Objects
curl "https://api.gapintelligence.com/api/v1/pricings?category_name=notebooks,desktops&date_collected=2018-06-01..2018-10-01"
-H 'Authorization: Bearer ***** Hidden credentials *****'
Pagination
With objects, the response contains additional information about the total number of objects on the page and total number of pages. The page parameter is used to paginate over pages.
curl "https://api.gapintelligence.com/api/v1/pricings?category_name=notebooks,desktops&date_collected=2018-06-01..2018-10-01&page=2"
-H 'Authorization: Bearer ***** Hidden credentials *****'
By default, the number of objects on one page equals or does not exceed 25. This value can be changed using the per_page parameter. However, I recommend using values not exceeding 50. In some cases, a large number of entries on one page can lead to response delays and may also require more resources to parse datasets.
Data Updates and Delta Changes
If your application directly connects to the API and does not store or cache data internally, any changes recorded on the gap intelligence database will be reflected in your application. However, there is another approach to working with the API, in which a local copy of a dataset is created from the API and your application uses this copy. This approach has many advantages over direct interaction, but also has a some challenges.
One challenge can be synchronization of local copy and the API. With a large dataset, synchronization can take up to several hours even if the data has not been changed since the last sync was ran. The ultimate goal is to identify only the data that has been modified or added.
The gap intelligence API allows for filtering objects by modified date. Yeah! When last_updated_date is passed, the response will contain only records that were updated, added or deleted from the passed date. This parameter can be combined with any combination of other parameters used for filtering or pagination. If the response returns no records, that means that there were no changes to the data since the provided date.
curl "https://api.gapintelligence.com/api/v1/pricings?category_name=notebooks,desktops&date_collected=2018-06-01..2018-10-01&page=1&last_updated_date=2018-09-01"
-H 'Authorization: Bearer ***** Hidden credentials *****'
This approach will allow you to update your local copy in seconds and keep it up-to-date much easier.
Summary
The gap intelligence API is a great solution for those who want to use raw data to create their own unique views and get impactful insights into their products' landscape. By using our API, you will receive immediate access to not only the latest information, but also to the entire gap intelligence historical database. Your favorite tool will get a second wind.
If you have questions, we are happy to answer them.
For more than 15 years, gap intelligence has served manufacturers and sellers by providing world-class services monitoring, reporting, and analyzing the 4Ps: prices, promotions, placements, and products. Email us at info@gapintelligence.com or call us at 619-574-1100 to learn more.
