Get Started with the Dock411 API

With Dock411 API v3, you can search and contribute to our databases shippers and receivers, their dock locations, and assessments and reviews of them. You can also search our database of dealers, parking locations, rest areas, restaurants, scales, truck washes, and weigh stations. You can use our data to enhance to your own applications. For example, if you market a transportation management sytem (TMS), you can add our data as a layer into your application, and provide significant value-add to your customers.

All calls to the Dock411 are metered. Please see the Authentication and Billing sections for more information.

After reading through this guide, be sure to check out the API Reference to see and test all available API requests with our sample data.

Before You Start

The Dock411 API is intended for developers, engineers, or anyone else who’s comfortable creating custom-coded solutions or integrating with RESTful APIs. If you think you may need some help integrating with the Dock411 API, one of our experts may be able to help develop a solution for your needs.

The REST architectural style is an integral part of API v3. If you’d like to learn more about REST before using the API, check out the Introduction to REST guide.

The design of the Dock411 API was heavily influenced by the best practices and recommendations in Apigee's “Web API Design”, by Brian Mulloy.

Environments

The Dock411 API is available in two environments: sandbox/test and production.

The production environment is our primary system, with real data and functionality. It is the "live" system, servicing the requests of end users through their apps and software.

The sandbox environment (aka "test") is a nearly exact replica of the production environment, for use by developers. It allows you to develop and test your code in a production-like setting without having to worry about causing harm to the live system. The sandbox environment is not covered by our SLA, does not have availability, performance, or consistency guarantees. End users should never access to the sandbox environment.

The sandbox and production environments have distinct sub-domain names. The sub-domain for the sandbox environment is api-test:

https://api-test.dock411.com/

The sub-domain for the production environment is simply api:

https://api.dock411.com/

It is up to you, the developer, to implement a system to utilize the proper sub-domain and API Keys and IDs within your application when it is accessing the sandbox or production environment.

SSL

For security and confidentiality, all requests must be made using HTTPS, regardless of the environment. Please ensure your connection library supports HTTPS.

Entities

Entities, sometimes referred to as "resources", are typically nouns like ‘docks’ or ‘weigh stations’. They represent the different types of data we maintain in our database. As a developer, you take actions on our entities using supported HTTP verbs and properly formatted URLs.

URL Path Patterns

There are a few common patterns for URL paths in the Dock411 API. In our experience, these patterns correspond to the most common use cases in typical user-facing applications.

Get All Entities

A very common use case is to get a list of all entities. The URL path pattern for this use case is

<entity type>/

where <entity type> is a plural noun for one the entities in our database. For example, the full URL to get a list of all known parking locations is

https://api-test.dock411.com/v3/parking_locations

Get a Single Entity

Another common use case is to get the details about a single entity, such as a dock. The URL path pattern for this use case is

<entity type>/{id}

where <entity type> is a plural noun for one of the entities in our database and {id} is its unique identifier. The identifier may be a D411 ID™ or the entity's UUID. For example, the full URL to get the details on a specific individual dock is

https://api-test.dock411.com/v3/docks/{id}

Get the Entities related to a Single Entity

A third common use case is to get all the entities related to a specific single entity. The URL path pattern for this use case is

<entity type>/{id}/<related entity type>

where <entity type> is a plural noun for one the entities in our database, {id} is its unique identifier, and <related entity type> is a plural noun for another one of the entities in our database. For example, the full URL to get all the reviews for a specific individual dock is

https://api-test.dock411.com/v3/docks/{id}/reviews

Authentication

All requests to our API must be authenticated by passing your API Keys and IDs in the HTTP headers. Complete our online form or email our API team to request a set of API Key and IDs. You will receive two sets of four keys and IDs, one each for the sandbox and production systems. Your HTTP client library should have built-in support for adding HTTP headers to any request, but here’s a quick example that shows how to authenticate with the --header option in curl:

curl --request GET \
--url "https://api-test.dock411.com/v3/gestalt" \
--header "x-api-key: <your_sandbox_api_key>" \
--header "x-api-id: <your_sandbox_api_id>" \
--header "x-api-pkey: <your_sandbox_api_pkey>" \
--header "x-api-pid: <your_sandbox_api_pid>" \

User Identification and Authorization

With a few exceptions, all requests to our API must include a user identifier. The identifier is used to record which user took an action or submitted data (for example, a review) and for analytical purposes. Dock411 uses JWT (JSON Web Tokens) as the underlying system in our API for user identification and authorization. The token must be included as a Bearer token in the HTTP Authorization: header.

The API provides an endpoint you will use to generate the initial token. Call /partner_users with the appropriate data to create a user in our system corresponding to a user in your system. The endpoint will return a unique User ID as well as the JWT.

Each request to the API will return an updated JWT in the response's X-Authorization header. Your code should store that token and include it as the Authorization: header with the next request to the API.

Typical Flow

Interactions with our API typically follow this flow:

1. Do you already have a user token?
   1. If not, call /partner_users to create a user. Pull the corresponding JWT for the user from the HTTP response's X-Authorization: header.
2. Make the call to your desired endpoint. Place the user JWT in the request's Authorization: Bearer <token> header.
3. The call's HTTP response will include an updated token in the X-Authorization header. Save that token and pass it in with the next call.

In short, every call to the API will return an updated token. Save that token and include it in the next call to the API.

HTTP Methods

The Dock411 API supports three HTTP methods for interacting with resources:

JSON

The Dock411 API supports JSON. So instead of XML, HTTP POST parameters, or other serialization formats, most POST and PUT requests require a valid JSON object for the body. The API Reference includes other examples, but here’s a quick look at the JSON format we’re looking for in POST and PUT requests:

{
  "brand_code" : "blue_beacon",
  "name" : "Oklahoma City North",
  "location" : "Oklahoma City North",
  "address1" : "7720 N Bryant Ave",
  "address2" : "",
  "city" : "Oklahoma City",
  "region" : "OK",
  "postal_code" : "73111",
  "country" : "USA",
  "main_phone" : "405-478-0833",
  "alt_phone" : "",
  "fax_phone" : "",
  "web_address" : "http://bluebeacon.com",
  "lat" : "35.5502120",
  "lng" : "-97.4585200",
  "manager_name" : "John Smith",
  "has_hand_wash" : "Y",
  "has_trailer_washing" : "Y",
  "has_reefer_washout" : "Y",
  "has_drybox_washout" : "N",
  "has_tanker_washout" : "Y",
  "has_livestock_washout" :"Y",
  "has_hopper_washout" : "Y",
  "has_trailer_deodorizer" : "N",
  "has_aluminum_brightening" : "N",
  "has_engine_wash" : "Y",
  "has_tire_dressing" : "Y",
  "has_undercarriage_rinse" : "N",
  "has_rainx" : "N",
  "has_citrushine" : "Y",
  "has_weathershield" : "Y",
  "has_managed_billing" : "Y",
  "current_tractor_only_price" : "41.50",
  "current_tractor_box_price" : "29.75"
  }

Parameters

There are four main categories of parameters for each endpoint in the Dock411 API: path, query string, request body, and response body. The API Reference includes a list of all available parameters for each possible request, but these sections offer an overview of the four main categories and their subcategories.

Path parameters

In an API URL, we include resource names and unique identifiers to help you figure out how to structure your requests. Resource names are fixed, but resource identifiers are required, so you need to replace them with real values. Let’s look at an example:

https://api-test.dock411.com/v3/docks/{id}

In that URL, there is one primary resource, docks. There is also one path parameters that you need to replace with real values: {id}. When you replace those values with actual data, your final URL should look something like this:

https://api-test.dock411.com/v3/docks/edf9d40d-2a13-448a-b775-8bc4fc706809

Query string parameters

We use query string parameters for filtering, pagination, and partial responses in the Dock411 API. The format for query string parameters is the full resource URL followed by a question mark, and the required or optional parameters:

https://api-test.dock411.com/v3/parking_locations?lat=41.9183185&lng=-88.3405545&within=5

Pagination

Paginate your API requests to limit response results and make them easier to work with. We use offset and limit in the URL query string to paginate to provide greater control over how you retrieve your data.

Offset defaults to 0, so if you use offset=1, you’ll miss the first element in the dataset. Limit defaults to 10. For example, this URL includes query string parameters for pagination:

https://api-test.dock411.com/v3/parking_locations?lat=41.9183185&lng=-88.3405545&within=5&offset=0&limit=10

Partial responses

Use field parameters to cut down on data transfers by limiting which fields the Dock411 API returns. For example, you may not need the full details of a resource, and can instead pass a comma-separated list of specific fields you want to include.

If you request a field that does not exist for the specified resource, the field will be ignored; the API will not throw an error. For example, the following URL uses the fields query string parameter to only include the wash name and location fields in the response:

https://api-test.dock411.com/v3/washes?lat=41.9183185&lng=-88.3405545&within=5&fields=name,location

Request body parameters

For PUT and POST requests, you may need to include a request body in JSON format. The API Reference shows you all the available request parameters for each endpoint, including required fields. The following example shows you how to create a new list with an HTTP POST request using curl (note the format of the --data option).

curl --request POST \
--url "https://api-test.dock411.com/v3/rest_areas" \
--header "x-api-key: <your_sandbox_api_key>" \
--header "x-api-id: <your_sandbox_api_id>" \
--header "x-api-pkey: <your_sandbox_api_pkey>" \
--header "x-api-pid: <your_sandbox_api_pid>" \
--header "Authorization: Bearer <user's JWT>" \
--header "content-type: application/json" \
--data "{"brand_code":"rest_area", "name":"Baldwin County Welcome Center", "location":"I-10 WB, MM 65.8", "address1":"", "address2":"", "city":"Baldwin", "region":"AL", "postal_code":"", "country":"USA", "main_phone":"", "alt_phone":"", "fax_phone":"", "web_address":"", "lat":"30.5757799", "lng":"-87.4185026", "reference_direction":"E", "description":"Interstate rest area", "cars_allowed":"Y", "trucks_allowed":"Y", "is_open_24_7":"Y", "hours":"24*7", "is_closed":"N", "closed_reason":"", "has_truck_parking":"Y", "has_overnight_parking":"Y", "num_overnight_parking_spots":"35", "num_overnight_parking_spots_available":"25", "has_camping":"N", "has_rv_dump":"N", "has_diesel":"N", "has_gas":"N", "has_handicap_facilities":"Y", "has_historical_marker":"N", "has_pet_area":"Y", "has_picnic_tables":"Y", "has_phones":"Y", "has_food":"Y", "has_vending_machines":"Y", "has_restrooms":"Y", "restroom_notes":"Very clean", "has_scenic_overlook":"N", "has_tdd":"N", "has_visitor_information":"Y", "has_water":"Y", "has_weather_monitoring":"Y", "has_wifi":"Y", "has_security":"N", "security_notes":"",
}" \
--include

Response body parameters

Every API call response includes headers and an optional JSON-formatted body.

The API Reference includes all possible response body parameters, but the following example shows the type of JSON-formatted response to expect from a POST request to the /docks endpoint:

{
    "docks": [
        {
            "id": "16c5de73-8470-445d-a310-5c9b5187bad1",
            "d411_id": "2ek-cp9-xlxi",
            "name": "Receiving",
            "shipper_receiver_name": "Costco Distribution Center",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        },
        {
            "id": "edf9d40d-2a13-448a-b775-8bc4fc706809",
            "d411_id": "d47-cts-9lzu",
            "name": "Receiving",
            "shipper_receiver_name": "Saddle Creek Logistics",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        },
        {
            "id": "a4002b33-6ecc-432c-9651-0b88d1623593",
            "d411_id": "i3l-ihl-71b4",
            "name": "Receiving",
            "shipper_receiver_name": "Wel Co",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        },
        {
            "id": "b32c04dc-f19d-49b6-9f86-f00df3eee152",
            "d411_id": "x7z-0uu-gefo",
            "name": "Receiving",
            "shipper_receiver_name": "Kimberly clark",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        },
        {
            "id": "678cdd79-1247-43dc-bd46-e62902202fc2",
            "d411_id": "d31-loa-5meu",
            "name": "Receiving",
            "shipper_receiver_name": "Armada ",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        },
        {
            "id": "33ac8b68-a35b-4f9a-a54f-c03174de0713",
            "d411_id": "lhd-6gj-ywdv",
            "name": "Receiving",
            "shipper_receiver_name": "Roosevelt Paper Co",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        },
        {
            "id": "5ffe852c-7b99-440c-8f10-87d05e693052",
            "d411_id": "kxm-12x-7yv7",
            "name": "Receiving",
            "shipper_receiver_name": "Plastic Film Corporation",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        },
        {
            "id": "3f9371c2-2a1a-4b80-969c-c1595aa19e60",
            "d411_id": "ju9-iju-apcb",
            "name": "Receiving",
            "shipper_receiver_name": "Plastic Film Corporation",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        },
        {
            "id": "29be2fb2-b7e7-4f2f-925f-9d3a952ba27c",
            "d411_id": "jwk-xn5-itbu",
            "name": "Receiving",
            "shipper_receiver_name": "Orbus",
            "reviewed_by_dock411": "N",
            "reviewed_by_company": "N"
        }
    ],
    "paging": {
        "matchingItems": "9",
        "totalPages": 1,
        "pageSize": 10,
        "currentPage": 1
    },
    "sorting": [],
    "bounding": {
        "ne_lat": 41.729927007299,
        "ne_lng": -86.979383547663,
        "sw_lat": 40.270072992701,
        "sw_lng": -89.020616452337
    },
    "consuming": {
        "time": "20 ms",
        "memory": "1.25 MB"
    }
}

Code Examples

Throughout the Dock411 API documentation, we include code examples so you know how to format your requests, and what kind of data to expect in return.

We use curl to show all requests. For example, the following code snippet shows a POST request to the /scales endpoint:

curl --request POST \
--url "https://api-test.dock411.com/v3/scales" \
--header "x-api-key: <your_sandbox_api_key>" \
--header "x-api-id: <your_sandbox_api_id>" \
--header "x-api-pkey: <your_sandbox_api_pkey>" \
--header "x-api-pid: <your_sandbox_api_pid>" \
--header "Authorization: Bearer <user's JWT>" \
--header "content-type: application/json" \
--data "{ "brand_code":"cat", "name":"Flying J Travel Plaza", "location":"Ross Clark Highway / Highway 231", "address1":"Ross Clark Highway / Highway 231", "address2":"", "city":"Dothan", "region":"AL", "postal_code":"36301", "country":"USA", "main_phone":"334-792-5152", "alt_phone":"", "fax_phone":"334-792-5293", "web_address":"http://www.pilotflyingj.com", "lat":"31.1920050", "lng":"-85.3998380", "certification":"cat", "has_axle_scale":"N", "has_platform_scale":"Y"}" \
--include

For most example requests, we use the same set of curl commands:

We use the long, double-dash form for curl options for readability, but you’re welcome to use the short, single-dash form if you prefer.

To show example responses, we include a JSON object in pretty-print format. For example, here’s a response to a GET request to the /hazards/{id} endpoint for API v3:

{
    "hazard": {
        "id": "465636d1-d086-11e6-8d24-34e6d739f9fa",
        "name": "Lost Creek",
        "lat": "33.7359722",
        "lng": "-87.3596111",
        "geohash": null,
        "created_by_user_first_name": "Dock411",
        "created_by_user_last_name": "Team",
        "created_by_user_handle": "dock411"
    },
    "photos": [],
    "consuming": {
        "time": "382 ms",
        "memory": "6.00 MB"
    }
}

Errors

We expose API errors in two ways: standard HTTP response codes and human-readable messages in JSON format. For example, the following code snippet shows an HTTP 405 error in the response headers:

HTTP/2 404 Not Found
content-type: text/html;charset=UTF-8
content-length: 2684
date: Mon, 10 Jul 2017 22:34:43 GMT
x-amzn-requestid: f84b1b14-65bf-11e7-9197-8ffeeaf40163
access-control-allow-origin: *
x-amzn-remapped-content-length: 2684
x-amzn-remapped-connection: keep-alive
vary: Host
x-amzn-remapped-server: Apache
access-control-allow-methods: GET,POST,OPTIONS,DELETE,PUT
x-amzn-remapped-date: Mon, 10 Jul 2017 22:34:43 GMT
x-cache: Error from cloudfront
via: 1.1 5a501e9cc6aa44f4c87ff790902a3af9.cloudfront.net (CloudFront)
x-amz-cf-id: CJ78qj19vYfxEGjuVkwWWKKHf7_tERS1Wyuef8Ic65vGJ8AD1GxLXw==

And this snippet shows the human-readable error as a JSON object:

{
    "message": "There was a problem with the request",
    "developer_message": "The data submitted has the following problems: lat is required but not found in the query string, lng is required but not found in the query string",
    "errors": [
        {
            "code": "lat_is_required",
            "field": "lat",
            "message": "Latitude is required",
            "more_info": null
        },
        {
            "code": "lng_is_required",
            "field": "lng",
            "message": "Longitude is required",
            "more_info": null
        }
    ]
}

For HTTP response codes, 4xx codes suggest a bad request. If you receive a 4xx response, we recommend reviewing the error glossary for more context to help you troubleshoot. 5xx errors suggest a problem on Dock411’s end, so if you receive a 5xx error, we recommend checking @Dock411Status and @Dock411_API on Twitter to see if we’re experiencing any system-wide issues.

Otherwise, feel free to contact our support team. If you contact support, we recommend including the complete request you’re trying to make and the error code and response you’re receiving so they can help as quickly as possible.

Throttling

To improve connections and experiences for all our users, we use some connection limits when we see suspicious activity or other overload. The specific limits are different for test and production systems and your contracted service level. The initial limits for requests to the test server are 10 per second and 10,000 per month. If you reach a limit, you’ll receive an error message.

Downtime

Dock411’s API has a 99.9% uptime. We’re rarely offline for planned maintenance, for example as part of major releases. If we do have downtime, we’ll tweet information from @Dock411App or @Dock411_API. We may also add a blog post or an in-app message, visible when you log in to your account.

Billing

Access to the Dock411 is limited to paying customers with active accounts. We offer a variety of "per month" and "per request" (aka, "pay-for-what-you-use") pricing plans.

We're happy to listen and advise you on the best ways to use our data to enhance your own applications. Contact us to become a customer or request more information about our API programs and pricing.

Roadmap

We’re always working to improve the Dock411 API. Check out the list of planned additions and enhancements for future releases, and sign up to receive Dock411 API announcements. This list is in alphabetical order, and we may add or remove items from the list as needed.

If one of these features is critical to your integration, please let us know.

• SDKs for Android and iOS