TMAS Web API Guide: Data Export & Management

TMAS API Key Management Guide

The TMAS Web API allows users to access and export traffic data seamlessly, integrating with third-party tools and applications. This guide provides instructions on creating, managing, and using API keys effectively.

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 activated on the chain and the counter device set to triggered configuration Note: This is ONLY available with the Real-Time T.M.A.S. subscription.

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.

Creating an API Key

Login to TMAS Select the Chain location in location options Expand Configure Select Manage Locations Select API Key(s) Select Add Key  Input API Key Name Check Off Traffic WEB API in permissions Click Add - Key will now appear in the Key Listing.

Locating the Location ID for the Chain and Locations

To find the Location ID for a Chain or individual locations: Log in to TMAS. Navigate to: Administration > Manage Locations. The list of locations will be displayed, including the Districts, Regions, and Locations. The Location ID is found in the corresponding column next to each location name. Use the appropriate Location ID in your API requests.

Obtaining a Group ID (optional)

To create a group and retrieve its Group ID: Find the Groups Management Section In TMAS, the Groups Management section is found in the left-side menu and select the desired group from the dropdown menu. Edit the Group  Click the edit (pencil) icon next to the selected group. Find the Group ID  The Group ID is displayed next to the ID label in the Import data from an existing group section. Copy this Group ID to use it in API requests. This Group ID can be used in API calls to filter data for locations within the selected group.

Viewing API Keys

• Only the user who created an API key can view and copy it.
• Other users will see the API key as masked with asterisks (*) and will not be able to access or copy it.
• The Created by User column displays the name of the user who generated the key.

Modifying or Deleting an API Key

• To edit an API key, click the pencil (edit) icon.
• To disable an API key, uncheck its permissions.
• To delete an API key, click the trash can icon. Note: Deleted keys cannot be restored.

User Deletion and API Key Handling

• If a user is deleted from TMAS, a prompt will appear for Chain and User Admins.
• The prompt provides two options:
  1. Disable the user account but keep the API key active – This allows the API key to continue functioning while preventing the user from logging in.
  2. Delete the user account and revoke the API key – This removes both the user and the API key.

This ensures that API access remains controlled even when user accounts are removed.

Using API Keys for Traffic Data Requests

API calls follow a standardized URL format, customizable based on parameters such as company, location, date range, and data interval.

API URL Structure:

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

Parameter Breakdown:

1. fromDate: Start date (MM/dd/YYYY-HH|mm). Time is optional. Appending 'i' returns data for incomplete days.
2. toDate: End date (MM/dd/YYYY-HH|mm).
3. interval: Data aggregation level:
   • 0 = Raw Traffic
   • 15 = 15 minutes
   • 30 = 30 minutes
   • 60 = Hourly
   • 1440 = Daily
   • 10080 = Weekly
   • 32767 = Occupancy Dashboard Info
4. hours: Business hours filtering:
   • 0 = Use predefined business hours
   • 1 = Use hours in fromDate
   • 2 = Custom hours spanning multiple days
5. reqType: Data export type:
   • td = Summarized traffic data
   • tdd = Recursive traffic data by location
   • tdl = Traffic data per device (interval ≥ 15)
   • tds = Traffic data per sensor (interval ≥ 15)
   • tdo = Occupancy dashboard info (interval = 32767)
   • tdor = Occupancy raw data (interval = 32767)
6. apiKey: Your unique API key.
7. locationId: The TMAS location ID (Chain, Region, District or Location level).
8. groupId (optional): Filters data for locations within a specific group.

API Call Limits & Best Practices

• Date Range Limit: Cannot exceed one month.
• Rate Limit: One call every two seconds.
• Minute-Level Data: Requires Fast Push configuration (LIVE DATA package).

Optimization Tips:

• Hourly Data Updates: Limit API calls to the last three hours to reduce system load.
• Historical Data Queries: When fetching data over multiple days, limit requests to 2-3 days and schedule them during off-peak hours (10 PM - 6 AM EST).

Live Examples (Demo Link)

Frequently Asked Questions

Q: Can I retrieve occupancy data without specifying a date range?

• Yes, for reqType=tdo or tdor, the occDate field returns the call time.

Q: How does the 'hours' parameter impact occupancy calls?

• Counters report continuously, but applying business hours filters out non-operational periods.

Q: What do occupancy level parameters mean?

• occLevelNow: Current occupancy.
• occLevel-1 to occLevel-4: Occupancy at previous intervals.
• occLevelMax: Maximum occupancy threshold.
• occLevelPct: Percentage of occupancy relative to max.

Troubleshooting API Issues

Issue: API key is not working

• Ensure the correct API key is used and has not been revoked.
• Verify that the API key is assigned the correct permissions.

Issue: Receiving 'Unauthorized' or 'Forbidden' response

• Check that the API key is associated with the correct Chain location.
• Confirm that the API key is not expired or disabled.

Issue: Data retrieval issues

• Verify that the date range does not exceed the one-month limit.
• Ensure that the interval parameter matches the required format.
• If fetching real-time data, confirm that Fast Push is enabled and there is a valid active real-time subscription plan. Counter must also have an assigned Real-Time license.

Issue: API rate limit exceeded

• API calls should be spaced at least two seconds apart.
• Reduce the frequency of API calls by batching data requests.

Issue: Unexpected empty response

• Double-check the location ID and group ID parameters.
• Ensure that there is available data for the specified time range.

Issue: Traffic data shows -1.0 values

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

Issue: 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”

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

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

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

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

• 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 

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

• Make sure the location you input is configured with occupancy functions

This guide provides a comprehensive overview of API key management in TMAS. For further assistance, contact support via chat help.storetraffic.com. for directly from T.M.A.S.