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.

Found in Manage Locations under administration, Chain / Bill to (Top Level of Location Tree) must be selected.

The User must have Chain and User permission type and pointing to top level of location tree in order to be able to access. 

LEARN MORE >> On Managing User Permissions

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) for traffic calls

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/tmas/manTrafExp?fromDate=[1]&toDate=[2]&interval=[3]&hours=[4]&reqType=[5]&apiKey=[6]&locationId=[7]&groupid=[8]

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. adding I at the end of the fromDate will return traffic for locations where the day was incomplete. Example: If a location which just opened only started reporting traffic in the afternoon of the day, it would not appear unless I was at the end of the fromDate=02/26/2020i 

• [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 intervalat 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
  • 32767 = Occupancy Dashboard Info

• [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. See type=tdv
    • tdv = Recursive traffic data 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 takes into consideration sensors marked as NOT viewable in reports and returns individual sums of all active sensors assigned to a location. See type=tds should you want to include sensors marked as NOT viewable in reports in the call.
    • tdo = Occupancy Dashboard Info with adjusted counts
      • Values returned include (storeId, color, occDate, occLevelNow, occLevel-1, occLevel-2, occLevel-3, occLevel-4, occLevelMax,  occLevelPct. Note: Interval=32767 must be used in call
    • tdor = Occupancy Dashboard Raw info with un-adjusted counts
      • Values returned include (storeId, color, occDate, occLevelNow, occLevel-1, occLevel-2, occLevel-3, occLevel-4, occLevelMax,  occLevelPct. Note: Interval=32767  must be used in call

• [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.

• [8] groupid=(optional) (Returns values only for locations who are a part of the group.  When combined with a district or region, values returns are only locations which are part of that district or region and members of the group.)
  • Group ID can be found in the group management function.
    1. Select previously created group from the group management drop down box
    2. Click edit button
    3. ID is highlighted in image below.

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 or less, fast push needs to be configured for the chain in T.M.A.S. Note: This is ONLY available with the LIVE DATA T.M.A.S. package.

API call Recommendations

Hourly Data Calls

• Limitation: If your application requires hourly data updates, be mindful of fair usage.
• Optimization: When updating data for numerous locations (e.g., over 40), limit your API calls to retrieve only the data from the past three hours. This approach helps manage the data volume and ensures efficient usage.

Historical Data Updates

• Recommended Practice: For updates on traffic data or similar metrics spanning several days:
• Data Range: Restrict updates to cover no more than 2-3 days of historical data.
• Scheduling: Conduct these updates during off-peak hours, ideally between 10 PM and 6 AM Eastern Standard Time (EST). This minimizes impact on server load and bandwidth during regular business hours.
   

Excessive Usage Example (Avoid)

• Unacceptable Practice: An example of excessive usage is making API calls every 15 minutes for data from over 40 locations, where each call retrieves two weeks' worth of data.
• Key Issue: This practice is inefficient as it involves redundant retrieval of large data sets, most of which is not newly generated information.

Live Examples (Demo Link)

FAQ

Q: Is a date range required when making a call for occupancy? 

A: No it is not required for calls of Type=tdo or Type=tdor as an occDate= will be returned indicating when the call was made.  All other type calls for date range (To/From) is required.

_______

Q: How does “hours” parameter effect the occupancy?

A: Counters report 24/7 to TMAS and counts are filtered by business hours, to avoid the inclusion of counting people who arrive before and after opening.

• 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 ignore 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

_______

Q: Understanding - occLevelNow, occLevel-1, occLevel-2, occLevel-3, occLevel-4, occLevelMax,  occLevelPct

A: 

occLevelNow = Occupancy Value @ time of the call

occLevel-1, occLevel-2, occLevel-3, occLevel-4 = Last 4 Intervals of occupancy for trending.

occLevelMax = Maximum Occupancy threshold set in TMAS for location.

occLevelPct = occLevelNow/occLevelMax for percentage of location used based on occupancy threshold.  

_______

Q: What is the difference between adjusted and un-adjusted?

A: Type=TDO is the raw unadjusted occupancy values without manual alterations throughout the day,

     Type=TDOR includes any manual adjustments made throughout the day (Recommend this type).

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

_____________________________________________________