logo
API docs by Redocly

HME API Reference (1.0)

Download OpenAPI specification:Download

HME API Support: apiintegrations@HME.com URL: https://www.HME.com/contact/

DXS Documentation

What is DXS RCD API?

DXS RCD API is a REST API that makes accessible the event-level data records for HME CLOUD connected timers (ZOOM and Nitro). The intended use is to provide short term access to detailed timing records for retrieval and insertion into a local database for business analytics use. It is not intended to be used as the back-end data storage or database source for those business analytics.

API Base URL

The HME CLOUD APIs can all be accessed by using the following base url:

https://api.hmecloud.com

Sending the request

HEADER Parameters

authToken

Service Account specific UID authentication key. This token is used by the server to validate the source of the Request, similar to a password.
Provided by HME after setting up a DXS subscription.

Security Scheme Type: API Key
Header parameter name: auth-key

serviceAccount

Name of the DXS Service Account.
Provided by HME after setting up a DXS subscription.

Security Scheme Type: API Key
Header parameter name: service-account

accountEmail

The email address for the Account Owner of the HME Cloud account. A service-account/auth-key pair can have multiple valid account-email associated. Only a single account-email can be requested at a time. Any store numbers referenced below must be valid store numbers for the account-email.

Security Scheme Type: API Key
Header parameter name: account-email

Requests

Get Stores

Get Stores Associated with DXS Service Account (Based on HEADER Parameters above)

query Parameters
Limit
string
Example: Limit=1

Max number of car records to include in a single response.
Max value of 5000
Defaults to 5000

Offset
string
Example: Offset=0

Offset into the complete set of the starting record to be returned. Used to page through the full result set when the result size is larger than the Limit.
Defaults to 0

Responses

Request samples 

curl -X GET "https://api.hmecloud.com/dxsmgmt/v1/store/list/default?Limit=1000&Offset=0" \
  -H "accept: application/json; charset=utf-8" \
 -H "auth-key: 11111111-2222-3333-4444-555555555555" \
  -H "service-account: Service Account Example"

Response samples

Content type
application/json
{
  • "total": 1,
  • "moreData": false,
  • "totalInSet": 1,
  • "offsetNext": null,
  • "data": [
    ]
}

Get Raw Car Data

This API lists Raw Car Data for a specified Service Account. There are several filters that may be used to limit the number of records that are returned.

query Parameters
StartDateTime
required
string
Example: StartDateTime=2022-09-21T06:00-08:00

The beginning date/time for filtering the returned car records.
Timezone is optional, UTC assumed if no timezone is provided.
The earliest valid date is 90 days before current date.
Example is 21 September 2022 6:00am Pacific Standard Time

EndDateTime
required
string
Example: EndDateTime=2022-09-23T22:00-08:00

The ending date/time for filtering the returned car records.
Timezone is optional, UTC assumed if no timezone is provided.
EndDateTime can be no more than 72 hours after the StartDateTime or an error will be returned.
Example is 21 September 2022 10:00pm Pacific Standard Time

StoreNumberList
string
Example: StoreNumberList=[1122,3344,"0011"]

Store numbers to filter results. Defaults to all stores.

BrandNames
string
Example: BrandNames=["HME","ClearComm"]

Brand names to filter results. Brand name string must match exactly with what is in the ZOOM/Nitro timer. Defaults to all brands.

IncludeIndependents
string
Example: IncludeIndependents=true

Selects whether Independent events are included in results. Defaults to false.

IncludePullOuts
string
Example: IncludePullOuts=true

Selects whether Pullout events are included in results. Defaults to false.

Limit
string
Example: Limit=1

Max number of car records to include in a single response.
Max value of 5000
Defaults to 5000

Offset
string
Example: Offset=0

Offset into the complete set of the starting record to be returned. Used to page through the full result set when the result size is larger than the Limit.
Defaults to 0

Responses

Request samples 

curl -X GET "https://api.hmecloud.com/dxs/v1/rcd/report/?StartDateTime=2019-10-01T11:00:00.000Z&BrandNames=\[\"BrandName\"\]&EndDateTime=2019-10-01T19T13:00:00.000Z&StoreNumberList=\[\"123456\"\]&IncludePullOuts=true&IncludeIndependents=true&Limit=1000&Offset=0" \
  -H "accept: application/json; charset=utf-8" \
  -H "account-email: test@hme.com" \
  -H "auth-key: 11111111-2222-3333-4444-555555555555" \
  -H "service-account: Service Account Example"

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": true
}

Request limitations

Date range limitations

Data up to 90 days old is available to to be requested. Requests for older data will return the response error 422: "Invalid start date. Please ensure the date is within last 90 days only."

The most recent data available is 15 minutes or more behind the time the request is received. Requests for more current data will be empty.

Time difference between the requests StartDateTime and EndDateTime can be at most 72 hours. If a larger time window is requested the return response will be be error 400: "dates_is_out_of_range".

Number of request limitations

The API allows the same request, with all the same input parameters, to be sent 3 times within a 60 minute period. Any additional request with those parameters will return response error 429: "Attempts_limitation_exceeded".

Additionally, any requests coming in faster than 10 a second will also generate a 429 error response.

Event names

Event type ZOOM
Single lane		 ZOOM
Y-lane		 ZOOM
Dual lane		 Nitro
Single Lane		 Nitro
Y-lane or Mobile Lane		 Nitro
Dual Lane
Pre-order Arrival
Pre-Alert
Pre-Loop
Pre-Warning		 Arrival
Pre-Alert
Pre-Loop
Pre-Warning
Split 1
Split 2		 Arrival 1
Arrival 2
Alert 1
Alert 2
Pre-Alert 1
Pre-Alert 2
Pre-Loop 1
Pre-Loop 2
Pre-Warning 1
Pre-Warning 2		 Pre Menu Pre Menu1
Pre Menu2		 Pre Menu1
Pre Menu2
Order point Menu Board
Menu Board1
Menu Board2
Menu 1
Menu 2
Order
Order 1
Order 2
Order Point
Order Point 1
Order Point 2		 Menu Board
Menu Board1
Menu Board2
Menu 1
Menu 2
Order
Order 1
Order 2
Order Point
Order Point 1
Order Point 2		 Menu Board1
Menu Board2
Menu 1
Menu 2
Order 1
Order 2
Order Point 1
Order Point 2		 Menu Board Menu Board1
Menu Board2		 Menu1
Menu2
Greet Greet
Greet 1
Greet 2		 Greet
Greet 1
Greet 2		 Greet 1
Greet 2		 Greet Greet 1
Greet 2		 Greet1
Greet2
Merge Merge 1
Merge 2		 Merge1
Merge2
Cashier Cashier
Window 2		 Cashier
Window 2		 Cashier 1
Cashier 2		 Cashier Cashier Cashier 1
Cashier 2
Delivery Delivery
Pickup
Pickup Window
Present
Presenter
Service
Window
Window 1
Window1		 Delivery
Pickup
Pickup Window
Present
Presenter
Service
Window
Window 1
Window1		 Delivery 1
Delivery 2
Present 1
Present 2
Service 1
Service 2		 Service Service Service1
Service2
Post-delivery Wait Area
Pull Forward
Pull Forward 1
Pull Forward 2		 Wait Area
Pull Forward
Pull Forward 1
Pull Forward 2		 Pull Forward 1
Pull Forward 2		 PF Window
Wait Area
Wait Area 1
Wait Area 2		 PF Window
Wait Area
Wait Area 1
Wait Area 2		 Wait Area 1
Wait Area 2
Wait Area 3
Wait Area 4
Independent Mobile
Mobile [1-15]
 Mobile
Mobile [1-15]		 Mobile
Mobile [1-15]

FAQ

  1. Can I include a timezone in the Start and End datetime parameters?

    • Yes, timezone can be included at the end.
    • Examples: 'Z' for UTC time; '-05:00' for EST; '-08:00' for PST. Daylight savings is not adjusted for in these times, and timezone value must be updated appropriately.

  2. Are the parameter names in the request case sensitive?

    • Yes. A request with parameter name of 'offset' will not be recognized while the parameter name 'Offset' will be recognized.

  3. What format should I use for the StoreNumberList?

    • An array of integers or an array of strings (with single or double quotes) is accepted. If a store number as it appears on the Cloud includes leading zeros (possible for Nitro timers only), then it must be a string and the leading zeros must be included.
    • Examples: [1001,245,9876]; ["1001","245","9876"]; ["1001","0245","9876"]

  4. Does it matter what order the parameters are included in the request?

    • No, the order does not matter.

  5. Data was requested and the returned response was 200:{"data": {"total": 0,...}. What does this mean?

    • It means that the Cloud data pool does not contain data that meet the requested parameters.
    • Reasons there may not be any data available:
      • Requested parameters are not correct
      • The timer is offline and has not uploaded data for the requested period
      • The timer did not record any valid Departure events during the requested period. This could be because there was no traffic through the drive-thru during that period, or all of the events could be exceptions (Pullins, Pullouts, Discards, etc). In this case, the Cloud Portal should be used to Remote Connect to the timer for verification.

  6. Once I have retrieved data for a time range, will it ever be updated/added?

    • No, data is sent from the timer in a first-in-first-out fashion. If a store record with departure time A has been retrieved, no records for that store prior to time A will be added or modified.
    • However, if you request time range [A-C] and the DepartureTime of the last returned record was B, where A < B < C, then there could still be records added later in the range [B-C].

  7. I received a response 429:"attempts_limitation_exceeded". What does that mean?

    • The Attempts_limitation_exceeded response comes back when you make the same request more than 3 times in 60 minutes. To avoid this, we recommend making changes to the requested Start or End times, or the Limit or Offset parameter. For initial development work and testing, it is recommended to set the Limit parameter to a lower number between 10 to 50. This limits the number of records returned in a single response to avoid dealing with large datasets when simply testing the processing. This can also be changed by 1 with each request to avoid the Attempts_limitation_exceeded error.
    • This response can also indicate that more than 10 requests per second have been made with the same auth-key no matter the parameters.

  8. When I make a request, how long may it take to return?

    • The DXS API will time out after 230 seconds.