To start using the API, you must first get an Authentication Token from the Credential Section using the Authenticate Method. If you are using the website, you can simply click the area under Body Sample and it will auto fill the userCredentials box with the proper format for you to enter your information. Otherwise, this should be in the format of:

{
"username": "Your Username Here",
"password": "Your Password Here"
}

  Assuming credentials are valid, the method will return an Authentication Token which will be valid for 1 Year. To get a new token, simply authenticate again. This will not invalidate any previously recieved token either, so it may be helpful in certain scenarios. FreightWaves handles the limits on accounts on the backend so the user does not have to worry about any of it, just get the token and you are set. Many of the messages have been designed to help you understand what went wrong. If at any point you are unsure or need more information, please feel free to contact us. There are 3 primary Data calls to retrieve Ticker information and they have been broken down into Item, Level, and Lane (each seperated into by date and by date range respectively). The primary call to retrieve a known valid ticker is the Item calls. It has the URL in the example format of https://api.freightwaves.com/data/OTRI/ATL/2019-02-20 (/2019-02-22 for range)

  To retrieve data from the API, the header must be appended with the token in the format: Authorization: Bearer token-here . For more specific code example information, scroll down to the example code section and utilize some of our example get requests to become more familiar with the API. For more in depth analysis and understanding, Postman is a useful tool to figure out the proper methodology and also provides code samples as well. There are several others as well and again you may reach out to us at anytime for more information or to become better aquainted with the system.

  From here, you can begin to access the API in earnest. Many of the calls use very specific terminology and require a bit of market understanding to properly utilize. In this section, we will describe the various terminology in detail.

Ticker

  There are many tens of thousands of data sets available in SONAR, and they are organized using a scheme of tickers. Much like a stock market ticker, the SONAR tickers describe the index being evaluated, as well as a qualifier that is used to display the index to the desired level of granularity. The Ticker is simply an index with a qualifier. Example ticker OTRI.ATL (Outbound Tender Reject Index for Atlanta)

Index

  The first portion of a ticker and indicates the data set being queried. Many values are updated daily, but some are updated Weekly or Monthly (checking Frequency will tell you how often we udpate a given Ticker). Check the LookUp call Indexes for more information and a complete list of valid indexes.

Qualifier

  The second and final portion of a ticker and indicates the market, region, city, lane, or general area that the ticker reflects upon. There are a great deal of qualifiers, but not all index and qualifier combinations represent a valid Ticker. For more information on valid tickers, use the LookUp call Qualifiers and Valid Tickers for more information.

Qualifier Level (Qualifier Code)

  This is one of the new additions to the new API. Qualifiers exist in groupings like NATIONAL and XMKT (refered to as Qualifier Code). This query allows you to search for all of the tickers that exist at a particular index and are part of a that Qualifier Level. For instance, OTRI.ATL would be the normal call if interested in Atlanta, but if you wanted more specific information about all of our X-Market data associated with OTRI, you would use the Levels query for OTRI.XMKT (which would return a large list of tickers for even a single day). For more information, use the LookUp call for Levels to determine what levels may be of interest in pulling bulk lists of Tickers. This call is intended to save query time by allowing for a broader return data set.

Qualifier Lane

  This is another new addition to the new API. One of the Qualifier Level types is specifically called Lanes. This is a direct reference to currently active shipping lanes. There are a large number of valid shipping lanes, but this call is specifically used to get ALL inbound and outbound lanes concerning a specific area. For example, the lanes query for OTRI.ATL would return all of our Inbound/Outbound lanes to/from Atlanta. For more information, use the LookUp call for Lanes to determine what lanes specific information you need. This call is intended to help target specific Lane data and save query time with those Lanes specifically.

Dates

  Dates are mainly self explanitory, but we do allow searching based on a specific Date-Time (which is not recommended), a specific Date, a specific Date range, or a specific Date-Time range.

Zip3

  Zip 3 is simply just the first 3 digits in a zipcode. The LookUp call Zip3 and Zip3 specific can give you the full list of Zip3's or the Specific Zip3's location data and how it relates to our markets.

Latest Data

  The LookUp call for Latest Data allows the user to search for a specific ticker's most recent data point. This will allow the user to determine how recent the data is for a given index and determine if they need to pull.

Frequency

  This is the rate which we update the particular Ticker. This value translates like this: A = Annually, Q = Quaterly, W = Weekly, F = Fortnight (Every other week), M = Monthly, D = Daily, I = Intra-Day (updated throughout the day multiple times). These can help you determine at which intervals you need to check for new data to prevent bad queries or duplicate data.

Rate Limiting

  FreightWaves API implements rate limiting for added security and to ensure the availability of data for all customers. Rate limits may vary by endpoint, so please evaluate the response headers returned from each request to direct your processes to pause or slow down as needed.

We rate limit our customers in 2 ways primarily:

1) We limit the number of RECORDS that can be pulled during a given time frame. This is negotiable with the FreightWaves Customer Success Team. For instance, we may allow a client to pull 10,000 records (rows of data) a day. Note that this does not mean "unique" data, so be sure to have local storage to eliminate duplicate queries.

2) We limit the number of REQUESTS per minute. This is fixed and is non-negotiable. Each endpoint will have its on Requests Per Limit Rate, so make sure to refer to the response headers for more specific rate limit information.

  Please note that many RECORDS can be retrieved per REQUEST. Here is a rough overview of why we've made the decision we have: "Everything You Need to Know About API Rate Limiting"

  In the event of too many requests, we will send back a code 429: Too many requests. This will mean that you have exceeded the current request per minute threshold. To prevent this, simply add a wait into your API query to prevent too many calls from executing at once.

For the most up to date information at any given time, check the various response headers with each call, the x-rate-limit object should provide all the necessary information.

Exceeding Rate Limits

  If you exceed the rate limit, you will receive a 429 (too many requests) status code. Upon receiving this status code, you should immediately halt all requests until the time specified by the x-rate-limit-reset header. You can evaluate the x-rate-limit-remaining and x-rate-limit-limit headers to help determine how many requests can be made before you exceed the limit. If you fail to assess the response headers,this could result in inconsistent data, application errors, or blacklisting.

Lookup Information

  As a general note, we do not charge customers for any lookup API calls. These exist to help the client build out a suitable way to tie everything into their own database.

  There are 2 primary methods for looking up information, Data and Lookup. The Lookup methods allow authenticated users to find what tickers, lanes, and levels are available for searching as outlined above. The Data methods will charge you for use, but allow the users to search specific tickers based on lanes and levels for a single date or date ranges. These should all be determined before using the Data calls. For a more in-depth look at what our data means, start here: FreightWaves Knowledge Center

Rate Limit Blacklist

  FreightWaves API has additional security built-in to prevent abuse via blacklisting. Blacklisting occurs when a process continues to query the API after the rate or record limit has been exceeded. Blacklisting times depend on how many subsequent requests are made after the limit has been exceeded and communicated back to the client. The typical time frame for lock-out is 10 minutes. As long as the process is stopped without continuing to attempt queries during this time frame, their should be no issues after the time frame is up. We are the major source for many organization's critical data infrastructure, so these security measures are to protect us as much as you the customer. Please let our customer success team know at any point if you become inconvenienced in any way.