Visits

We have two variants of the Visits endpoint. Both have the same requirements in terms of making a request for data.

• /visits/standard

  Requires OAuth scope visits/standard.read

• /visits/plus

  Returns all the fields from the 'standard' endpoint, with some additional fields.
  HGEM will provide access to the 'plus' endpoint where there is a business need to do so.
  Requires OAuth scope visits/plus.read.

If you try to access a visits endpoint that your API Key or Access Token does not entitle you to access, you will receive a 403 - Forbidden response.

---

Making requests to the /visits endpoint

To make a valid request, you will need to supply ALL of the following parameters on the querystring of the endpoint URL:

Parameter name	Data type	Permitted values
HgemClientId	Integer	Must be a value greater than zero
FromDate	ISO date	Format is yyyy-mm-dd
ToDate	ISO date	Format is yyyy-mm-dd
Skip	Integer	Must be a value greater than or equal to zero
Take	Integer	Must be a value greater than zero

Optional parameters:

Parameter name	Data type	Permitted values
HgemBrandId	Integer	Must be a value greater than zero
VisitTypes	Comma-separated list of 2-character strings	See VisitTypes

• The parameter names are NOT case-sensitive.
• Please review the Authentication page for information on how to authenticate your requests.
• Optional HgemBrandId parameter - Not required unless instructed by HGEM to use.
• Optional VisitTypes parameter:
  • If omitted, will default to all Visit Types assigned to your api key.
  • If you try to access visit types that your API Key does not entitle you to access, you will receive a 403 - Forbidden response.
    

---

Query parameter limits

Please review the Rate Limiting page for information on request rate limits that HGEM impose.
In addition, HGEM impose limits on the amount of data that can be returned on a single request for the visits endpoints.
These request parameter limits are:

Parameter name	Limit
Take	Maximum value = @Azure@ApiGateway:QuerySettings:MaxTakeSize@Azure@
FromDate	Must not be today or in the future
ToDate	Must not be today or in the future
FromDate & ToDate	Maximum range of @Azure@ApiGateway:QuerySettings:VisitsForLastNoOfDays@Azure@ days
	ToDate must be greater than or equal to FromDate
	For a single day, set both FromDate and ToDate to the same value

Skip & Take paging

After your first successful request, you should do a comparison of the number of visits returned against the Take value you used.
If your response contained the same number of visits as the Take value you used, it is possible that there are more visits that could be returned.
In this case, you should make another call with the same parameters, except with an appropriate Skip, to check for any further results.

---

Example requests

Example cUrl:

curl -X GET https://results-api.hgem.com/visits/standard?hgemclientid=123456&fromdate=2019-05-01&todate=2019-05-08&skip=0&take=100
  -H "hgem-api-key: YOUR-API-KEY-GOES-HERE" 
  -H "Authorization: Bearer Some_really_long_base64_encoded_text_that_makes_up_your_JWT_access_token" 

Example Raw HTTP/1.1:

Below is an example request made by Postman

GET /visits/standard?hgemclientid=123456&skip=0&take=250&fromdate=2019-05-23&toDate=2019-05-30 HTTP/1.1
Host: results-api.hgem.com
hgem-api-key: YOUR-API-KEY-GOES-HERE
Authorization: Bearer Some_really_long_base64_encoded_text_that_makes_up_your_JWT_access_token
User-Agent: PostmanRuntime/7.13.0
Accept: */*
Cache-Control: no-cache
Postman-Token: e7fd3f29-dad4-4e82-8af8-dca71a93925e,2a369656-b09b-4212-9799-68f2fa4459af
accept-encoding: gzip, deflate
Connection: keep-alive
cache-control: no-cache

---

Possible API responses

HTTP Response Status	Description
200 - OK	Success - response body will contain your data
400 - Bad Request	You have made a malformed request that cannot be processed (with the same parameters), even if you were to retry
401 - Unauthorized	You have either failed to provide an API Key, an access token, or requested an endpoint you are not entitled to use
403 - Forbidden	You have requested results data you are not entitle to access. Change your query
429 - Too Many Requests	You have breached our API rate limits, try again later
500 - Internal Server Error	The API request has resulted in an error which we have not been able to provide further information for.
503 - Service Unavilable	The API is currently unavailable, try again later

See here for further information on HTTP response codes.

---

Successful Requests

When you make a successful request on the /visits endpoint, the response will be as per the example below:
Please review the Data Dictionary page for information on interpreting the data returned from your requests.

• Content-Type: application/json

• Body content:

    {
    	"data": {
    		"visits": [
    			{
    				"visitId": 1234567,
    				"clientId": 123456,
    				"clientName": "Example Client",
    				"brandName": "Example Brand Name #1",
    				"branchId": "9871",
    				"branchCode": "ABC001",
    				"branchName": "Example Branch Name #1",
    				"visitType": "MV",
    				"visitScore": 100,
    				"recommendScore": 10,
    				"recommendComment": "Example comment #1",
    				"visitDateTime": "2019-05-21T19:45:18",
    				"modificationDate": "2019-05-22T10:35:07",
    				"visitSource": "Example Visit Source",
    				"sections": [
    					{
    						"name": "Example Section Name",
    						"score": 100,
    						"questions": [
    							{
    								"subject": "Example Question Subject",
    								"score": 100.00,
    								"analysisTag": "Example Tag",
    								"category": "Example Category",
    								"dish": "Example Dish"
    							}
    						]
    					}
    				]
    			},
    			{
    				"visitId": 1234568,
    				"clientId": 123456,
    				"clientName": "Example Client",
    				"brandName": "Example Brand Name #2",
    				"branchId": "9872",
    				"branchCode": "ABC002",
    				"branchName": "Example Branch Name #2",
    				"visitType": "TA",
    				"visitScore": 100,
    				"recommendScore": 10,
    				"recommendComment": "Example comment #2",
    				"visitDateTime": "2019-05-21T18:33:04",
    				"modificationDate": "2019-05-22T10:35:07",
    				"visitSource": "Example Visit Source",
    				"sections": [
    					{
    						"name": "Example Section Name",
    						"score": 100,
    						"questions": [
    							{
    								"subject": "Example Question Subject",
    								"score": 100.00,
    								"analysisTag": "Example Tag",
    								"category": "Example Category",
    								"dish": "Example Dish"
    							}
    						]
    					}
    				]
    			},
    			{
    				"visitId": 1234569,
    				"clientId": 123456,
    				"clientName": "Example Client",
    				"brandName": "Example Brand Name #3",
    				"branchId": "9873",
    				"branchCode": "ABC003",
    				"branchName": "Example Branch Name #3",
    				"visitType": "OF",
    				"visitScore": 100,
    				"recommendScore": 10,
    				"recommendComment": "Example comment #3",
    				"visitDateTime": "2019-05-21T18:30:52",
    				"modificationDate": "2019-05-22T10:35:07",
    				"visitSource": "Example Visit Source",
    				"sections": [
    					{
    						"name": "Example Section Name",
    						"score": 100,
    						"questions": [
    							{
    								"subject": "Example Question Subject",
    								"score": 100.00,
    								"analysisTag": "Example Tag",
    								"category": "Example Category",
    								"dish": "Example Dish"
    							}
    						]
    					}
    				]
    			}
    		]
    	}
    }
  

• Note: 'MV' type visits go through a review and auditing process and the scores are subject to change for up to 24hrs after the visit is complete. It is your responsibility to determine how recent you request visit data. It is also your responsibility to check for data that may have changed, if you requested data for 'yesterday'.

---

Bad Requests

When you make API calls that result in a response of 400 - Bad Request, you may also get a ProblemDetails response in the body.

An example response would be:

• Content-Type: application/problem+json
• Body content:

    {
    	"title": "Bad Request",
    	"status": 400,
    	"detail": Unable to process the requested query. See 'errors' for further information.,
    	"instance": "urn:hgem:api:results:error:aaf0b99b-d709-4efb-9138-1f1b231169e1",
    	"errors": [
    		"'hgemClientId' must not be empty.",
    		"'visitTypes' must be 2 alpha characters. Requested value was 'XYZ'",
    		"'skip' must be greater than or equal to '0'.",
    		"'fromDate' is not in the expected format 'yyyy-mm-dd'."
    	]
    }