Overview

This article explains how to use the SMS Web API Export On Demand system to quickly access and export TMS traffic data from a web interface in an XML format. The WEB API is a powerful tool as it allows direct and instant access to the database data without the need for a custom export or report generation. Once exported, the data can be easily customized to allow integration with a multitude of third party tools, software, or database.

Creating an API KEY(s)

1. Login to TMAS
2. Select the Chain location in location options
3. Expand Configure
4. Select Manage Locations
5. Select API Key(s)
6. Select Add Key 
7. Input API Key Name
8. Check Off Traffic WEB API in permissions
9. Click Add - Key will now appear in the Key Listing. 

Editing and Deleting existing API Key(s)

• Click on the Pencil Icon next the API Key row to edit (Use to Disable by Unchecking Permission)
• Click on the Trash Can Icon next the API Key row to Delete
• *NOTE* Deleted Keys cannot be returned to use.

Using the API Key(s)

The WEB API is called using a standard URL customized for your company, location, date range, interval, business hours filter, and export type. The basic structure of the URL is shown in the link below:

https://www.smssoftware.net/tms/manTrafExp?fromDate=[1]&toDate=[2]&interval=[3]&hours=[4]&reqType=[5]&apiKey=[6]&locationId=[7]

Each of the highlighted numbers in bracket represent an area that can be customized:

• [1] The starting date of date range from which you want to export the data. The complete format is MM/dd/YYYY-HH|mm but the HH and mm are not mandatory and can be ignored if selecting traffic only by hours or by day.
• [2] The ending date of the date range from which you want to export the data. The format is the exact same as the starting date described above.
• [3] The interval at which the traffic data will be generated.
  • 0 = Interval not applicable (Raw Traffic)
  • 15 = 15 minutes
  • 30 = 30 minutes
  • 60 = Hourly
  • 1440 = Daily
  • 10080 = Weekly
• [4] If you have business hours defined for your company in T.M.A.S., you can use this option to easily filter the hour ranges. Note* Applies to ONLY Type=T* with interval >0
  
  • 0 = Use business hours (If hours are specified in the API Call this is overrides to 1)
  • 1 =  Use the hours provided in the fields [1] Only and ignors end hour in [2] however end time must still be present.
    • Best used for Real Time traffic calls for refreshing data and not to call historical data.
  • 2 = Custom Hours over multiple days - Use the hours provided in the fields [1] and [2]
    • Uses the hours as a range
• [5] The export type of the data export.
  • td = Traffic Data (Returns a summed total of traffic for the location and any sub-locations where the location is a parent and where the device sensors are marked as viewable in T.M.A.S. reports).  Values returned include (TrafficData, TrafficValue, StoreID).
    • tdd = Recursive traffic data or raw traffic data - (Output is similar to TD, however shows each individual location summed and not totals by Chain, District or Region)
      • Values returned include (TrafficData, TrafficValue, StoreID).
    • tdl = Recursive traffic data per devices (interval must be set to 15 or higher) 
      • Values returned include (TrafficData, TrafficValue, StoreID|Device Label). Note: This output type does NOT consider devices_sensors marked as NOT viewable in reports and returns the traffic sum of all active devices assigned to a location.
    • tds = Recursive traffic data per sensors (interval must be set to 15 or higher) 
      • Values returned include (TrafficData, TrafficValue, StoreID|Sensor Label|Unique Sensor ID)Note: This output type does NOT consider sensors marked as NOT viewable in reports and returns individual sums of all active sensors assigned to a location.
  • qd = Queue Data
    • qdd = Recursive
    • qdc = Last three
    • Can also add & queuename= to specify a single queue name
  • dw = Dwelling data
    • dwc = Aggregated
• [6] apiKey= provided by TMAS application
• [7] The T.M.A.S. location ID of the location you want to export traffic data from. Can use location type Chain, Region or Store Level ID.  Found in the manage locations section under configure.

API call Limitations

• The date range may not exceed one month.

• The T.M.A.S. Web API has a rate limit of one call every two seconds.

• To access traffic data by one minute intervals, fast push needs to be configured for the chain in T.M.A.S.

Live Examples (Demo Link)

Example: https://www.smssoftware.net/tms/manTrafExp?fromDate=12/04/2017&toDate=12/10/2017&interval=0&hours=0&reqType=tdd&apiKey=V1THYJNE468F6KWQRVMQX5FF5KEYY954&locationId=salesd

Bug Fixes

Troubleshooting

Problem: Error 400 - Website not found

Solution: Verify API URL - Make sure it is formatted correctly as per the example in this article as well as has the complete API Key generated from the TMAS application.

_____________________________________________________

Problem: Traffic data shows 0

Solution: Make sure there is data for this date range by running a totaling report in T.M.A.S.

_____________________________________________________

Problem: Traffic data shows -1.0 values

Solution: -1.0 Traffic Data returned indicates that there was no traffic reported by the counter for this time interval.  Verify the date / time requested and/or Verify if the counter hardware was functioning properly during this time and follow the appropriate troubleshooting process.

_____________________________________________________

Problem: Error message: “The Date parameters given in (DATE RANGE) are either formatted erroneously, are in the future or do not make sense to the system”

Solution: 

• ✓ Make sure you have entered a valid date, and that the last interval is not at a future time.
• ✓ Make sure the date range does not exceed one month

_____________________________________________________

Problem: Error message: “The parameters (interval and/or hours) given do not respect the authorized values”

Solution: Make sure the interval is valid, as explained in the Usage section

_____________________________________________________

Problem: Error message: "An underlying DB Issue is preventing the server from displaying any data, please contact your database administrator."

Solution:  Verify your Date range (FROM&TO) format is MM/DD/YYYY in the API call URL

• Incorrect: &fromDate=6/12/18&toDate=6/12/18
• Correct: &fromDate=6/12/2018&toDate=6/12/2018

_____________________________________________________

Problem: Error message: “The given location doesn’t have any queue”.

Solution:  Make sure the location you input is configured with occupancy functions

_____________________________________________________

Problem: Error message: "Forbidden Access"

Solution: Verify that the API key and/or location ID is correct and exists

_____________________________________________________