Best Practices

General

• The API is designed with developers in mind; we prefer that the application developer contact Expeditors for support instead of the end user. A support process between the end user and application developer should be in place if required. Provide a client ID when contacting technical support.  
  

• This is a RESTful service. The Expeditors Shipment Tracking API attempts to conform to the design principles of Representational State Transfer (REST) and relevant W3C HTTP/1.1 standards. The API uses the JSON data format for responses.  
  

• Use proper encoding for HTTP requests. Only use UTF-8 character encoding. Parameter values should be converted to UTF-8 and URL encoded according to W3C standards. 
  

• Implement good error handling. Our API follows the W3C HTTP/1.1 standards for general error responses. 400 errors mean there is a problem with the request and it SHOULD NOT be repeated without fixing the problem. 500 errors mean that Expeditors is experiencing some kind of technical failure and the client MAY retry sending the request at a later time. For more specific information on error handling, see the Error Codes section.   

• Don't use spaces or other non-alphanumeric values. Please do not include encoded spaces or other non-alphanumeric values. This will cause senders to see a HTTP 500 error.

• Moderate token requests. Large quantities of token requests within a few minutes will cause HTTP 500 errors and also potentially cancel out other token requests. If you can space out token requests, that would help ease this problem.   

• Optimize Shipment Requests. Making multiple requests for shipment details will yield the same data for large portions of the life of the shipment*. This results in unnecessary processing of retrieved information, and in cases where charges are accrued, additional costs can add up quickly. Using the ‘GET shipments’ call to retrieve multiple shipments and their current status. If the status has changed, subsequent calls can be made to specific shipments for the desired details. Making one call to get a summary of all shipment states eliminates unnecessary detail calls, maintains timely retrieval of current state, and lowers overall costs, if applicable.

  *Ocean shipments can remain in transit for several days or weeks, and shipment records will remain largely static during this time. Air and road (transcon) shipments are updated more quickly but can still be static for hours at a time. The shipment status changes to reflect any activities that materially changes what is known about any given shipment.

Security

• Tokens are passwords. Keep in mind that the consumer key and secret, bearer token credentials, and the bearer token itself grant access to make requests on behalf of an application. These values should be considered as sensitive as passwords and must not be shared or distributed to unauthorized parties.

Expeditors Tracking

• Rate limiting restricts the number of times you can request resources from the API within a certain time window. Limit the number of times a resource (shipment, status, container, etc.) is tracked to what is necessary for business needs.

• Responses have default pagination. Clients may access a maximum of 1000 rows of tracking data when no pagination parameters (sizeLimit and offset) are specified. To access data after the first thousand rows, the request may give specific pagination parameters.