TMAS - Web API

Traffic Exporting

Table of Contents

    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]&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 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
      • 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=32676 must be used in call
        • tdor = Occupancy Dashboard Raw info with un-adjustedcounts
          • Values returned include (storeId, color, occDate, occLevelNow, occLevel-1, occLevel-2, occLevel-3, occLevel-4, occLevelMax,  occLevelPct. Note: Interval=32676 must be used in call
      • 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.


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

    Live Examples (Demo Link)


    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

    _____________________________________________________

    header-top-left-border Created with Sketch.
    header-top-right-border Created with Sketch.