We integrate with a lot of APIs here at Freightview, and we even have a rating API of our own. We connect with carrier APIs for rating, dispatching, and tracking. We also work with the APIs of other services that we depend on to keep Freightview running smoothly, like Stripe and Close.io. API technology powers the Freightview platform, creating an instant and seamless experience for all our users.
Maybe you're building a new API so your company can get their rates in front of more people. Or, maybe you've got an existing API that needs some tweaking. Here's what we're looking for when we integrate with an API:
As far as the technology behind the API, it doesn't matter too much to us and it probably depends a lot upon your existing infrastructure. But, we do have a few suggestions:
We prefer simple REST APIs using JSON as the data format, but XML is good too. We're not big fans of SOAP APIs. If you have the choice of SOAP and REST, we recommend you choose REST every time.
For authentication, the simplest way to do this is to just use cryptographically strong API tokens. We also strongly recommend that every API be secured with SSL using SHA-2.
How it works
Let's talk about what a basic and a more advanced rating API request and response typically looks like:
The request should have everything you need to return a rate for that shipment. A basic rating API usually supports:
- Pickup date
- Origin information
- Postal code
- Destination information
- Postal code
- Commodity information
- Freight class
- Handling units
- Packaging type
- Accessorial charges
- Limited access pickup/delivery
- Liftgate pickup/delivery
- Arrival notice/schedule
- Inside pickup/delivery
- Tradeshow pickup/delivery
- Residential pickup/delivery
- Construction site pickup/delivery
- Protect from freeze
- Account number
- Payment terms
- Third party
More advanced LTL rating APIs support:
- Product dimensions
- NMFC numbers
- Blind shipment accessorial
If you support multiple service types, such as Guaranteed or Expedited services, returning rates for all service types and service options with one API call is a really nice feature for us.
Error handling is also important when it comes to building APIs that are easy to work with. Having a standard way of returning error messages is important, and we recommend making use of HTTP status codes to give more context to an error. Writing error messages that don't require internal knowledge to understand is also very important when building APIs that are to be utilized by third parties.
Most of the rating APIs that we work with return:
- Interline indicator
- Total cost for each service type
- Transit days for each service type
- Quote number for each service type
More advanced rating APIs can have:
- Charge breakdown
- Each accessorial
- Fuel surcharge
- Tariff name
- Terminal information
Some carriers offer pallet or FAK pricing for specific customers or lanes. Ideally, a rating API supports these types of pricing, but if that's not quite the case yet, we'd prefer that a rating API returns an error instead of a rate that doesn't take into account the shipper's pallet pricing.
A commonly overlooked part of building a developer-friendly API is writing the documentation. This is where many skimp, but good documentation is essential if you want people to use your API.
As for where to host your API documentation, we recommend a tool like Readme.io that focuses on hosting API documentation. Just about anything is better than a Word document.
Defining all the different possible values and the various formats is crucial:
- Pickup date format
- Accessorial names and codes
- Possible values for packaging types
- Possible values for freight classes
Having a couple different examples with the request, the response, the URL, HTTP method, any relevant HTTP headers, and status codes can be very useful when starting up an initial API integration.
We hope this is a helpful guide for what considerations to make when starting a new freight rating API and also for improving existing freight rating APIs.
For an example of a carrier's rating API and documentation that we are fond of, check out Dayton Freight's API docs.
The Freightview rating API also puts many of these ideas into practice.