From e4ab46c1c6588e57237e1aa7902ccb1f850c56c3 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 20 Apr 2026 00:25:42 +0000 Subject: [PATCH] Fix writing style and tone consistency across docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Standardize voice, fix typos, and align older pages with the established style guide (second person, active voice, sentence case headings). Changes across 14 files: - Replace first person (we/our/I) with second person (you) or product name (Terminal49) for consistency with newer pages - Fix typos: frieght→freight, neeed→need, demonstates→demonstrates, autorization→authorization, Wheverever→Wherever, indidicates→indicates, succeded→succeeded, teminal→terminal, webook→webhook, adn→and, pase→paste, wheter→whether - Fix its/it's errors - Convert title case headings to sentence case - Shorten overly long sentences (30+ words) - Remove informal language (nifty, getting your feet wet, love Postman) - Standardize the JSON:API explanation note across 3 pages - Fix passive voice where active voice is clearer Generated-By: mintlify-agent --- .../list-shipments-and-containers.mdx | 16 +++---- .../receive-status-updates.mdx | 16 +++---- docs/api-docs/getting-started/start-here.mdx | 8 ++-- .../tracking-shipments-and-containers.mdx | 48 +++++++++---------- .../in-depth-guides/adding-customer.mdx | 20 ++++---- .../in-depth-guides/event-timestamps.mdx | 6 +-- docs/api-docs/in-depth-guides/quickstart.mdx | 16 +++---- .../rail-integration-guide.mdx | 8 ++-- .../in-depth-guides/rate-limiting.mdx | 2 +- .../in-depth-guides/terminal49-map.mdx | 4 +- .../in-depth-guides/terminal49-widget.mdx | 8 ++-- .../tracking-request-lifecycle.mdx | 16 +++---- docs/api-docs/in-depth-guides/webhooks.mdx | 6 +-- .../useful-info/tracking-request-retrying.mdx | 8 ++-- 14 files changed, 90 insertions(+), 92 deletions(-) diff --git a/docs/api-docs/getting-started/list-shipments-and-containers.mdx b/docs/api-docs/getting-started/list-shipments-and-containers.mdx index a0a68d3..e460576 100644 --- a/docs/api-docs/getting-started/list-shipments-and-containers.mdx +++ b/docs/api-docs/getting-started/list-shipments-and-containers.mdx @@ -16,11 +16,11 @@ keywords: After you've successfully made a tracking request, Terminal49 will begin to track shipments and store relevant information about that shipment on your behalf. -The initial tracking request starts this process, collecting available data from Carriers and Terminals. Then, Terminal49 periodically checks for new updates adn pulls data from the carriers and terminals to keep the data we store up to date. +The initial tracking request starts this process, collecting available data from carriers and terminals. Terminal49 then periodically checks for new updates and pulls data from carriers and terminals to keep the stored data up to date. You can access data about shipments and containers on your tracked shipments any time. We will introduce the basics of this method below. -Keep in mind, however, that apart from initialization code, you would not usually access shipment data in this way. You would use Webhooks (described in the next section). A Webhook is another name for a web-based callback URL, or a HTTP Push API. They provide a method for an API to post a notification to your service. Specifically, a webhook is simply a URL that can receive HTTP Post Requests from the Terminal49 API. +In practice, you would typically use webhooks (described in the next section) rather than polling for shipment data. A webhook is a callback URL that receives HTTP POST requests from the Terminal49 API whenever tracking data changes. ## List all your tracked shipments @@ -46,8 +46,8 @@ If you had trouble adding your first shipment, try adding a few more. ``` -> ### Why so much JSON? (A note on JSON API) ->The Terminal49 API is JSON API compliant, which means that there are nifty libraries which can translate JSON into a fully fledged object model that can be used with an ORM. This is very powerful, but it also requires a larger, more structured payload to power the framework. The tradeoff, therefore, is that it's less convenient if you're parsing the JSON directly. Ultimately we strongly recommend you set yourself up with a good library to use JSON API to its fullest extent. But for the purposes of understanding the API's fundamentals and getting your feet wet, we'll work with the data directly. +> ### Why so much JSON? (A note on JSON:API) +>The Terminal49 API is JSON:API compliant. JSON:API libraries can translate the response into a full object model compatible with an ORM, which is powerful but produces larger, more structured payloads. If you parse JSON directly, this can feel verbose. For production use, consider adopting a [JSON:API client library](https://jsonapi.org/implementations/#client-libraries) to get the most out of the format. For this tutorial, you will work with the data directly. ## Authentication @@ -55,18 +55,18 @@ The API uses HTTP Bearer Token authentication. This means you send your API Key as your token in every request. -Webhooks are associated with API tokens, and this is how the Terminal49 knows who to return relevant shipment information to. +Webhooks are associated with API tokens, which is how Terminal49 identifies which account to send shipment updates to. ## Anatomy of shipments JSON response Here's what you'll see come back after you get the /shipments endpoint. -Note that for clarity I've deleted some of the data that is less useful right now, and replaced them with ellipses (...). Bolded areas are also mine to point out important data. +For clarity, some fields have been replaced with ellipses (...) and key areas are bolded. -The **Data** attribute contains an array of objects. Each object is of type "shipment" and includes attributes such as bill of lading number, the port of lading, and so forth. Each Shipment object also has Relationships to structured data objects, for example, Ports and Terminals, as well as a list of Containers which are on this shipment. +The **data** attribute contains an array of objects. Each object is of type `shipment` and includes attributes such as bill of lading number and port of lading. Each shipment object also has relationships to structured data objects like ports and terminals, as well as a list of containers on the shipment. -You can write code to access these structured elements from the API. The advantage of this approach is that Terminal49 cleans and enhances the data that is provided from the steamship line, meaning that you can access a pre-defined object definition for a specific port in Los Angeles. +You can access these structured elements through the API. Terminal49 cleans and enhances the data from the shipping line, so you get a pre-defined object for each port, terminal, and other entity. ```jsx diff --git a/docs/api-docs/getting-started/receive-status-updates.mdx b/docs/api-docs/getting-started/receive-status-updates.mdx index 5785907..a57f38b 100644 --- a/docs/api-docs/getting-started/receive-status-updates.mdx +++ b/docs/api-docs/getting-started/receive-status-updates.mdx @@ -16,7 +16,7 @@ keywords: Terminal49 posts status updates to a webhook that you register with us. -A Webhook is another name for a web-based callback URL, or a HTTP Push API. They provide a method for an API to post a notification to your service. Specifically, a webhook is simply a URL that can receive HTTP Post Requests from the Terminal49 API. +A webhook is a callback URL that receives HTTP POST requests from the Terminal49 API whenever tracking data changes. The HTTP Post request from Terminal49 has a JSON payload which you can parse to extract the relevant information. @@ -35,7 +35,7 @@ The API uses HTTP Bearer Token authentication. This means you send your API Key as your token in every request. -Webhooks are associated with API tokens, and this is how the Terminal49 knows who to return relevant shipment information to. +Webhooks are associated with API tokens, which is how Terminal49 identifies which account to send shipment updates to. ## Anatomy of a webhook notification @@ -43,13 +43,13 @@ Here's what you'll see in a Webhook Notification, which arrives as a POST reques For more information, refer to the Webhook In Depth guide. -Note that for clarity I've deleted some of the data that is less useful right now, and replaced them with ellipses (...). Bolded areas are also mine to point out important data. +For clarity, some fields have been replaced with ellipses (...) and key areas are bolded. -Note that there are two main sections: +There are two main sections: **Data.** The core information being returned. -**Included**. Included are relevant objects that you are included for convenience. +**Included**. Related objects included for convenience. ```jsx { @@ -131,8 +131,8 @@ Note that there are two main sections: } ``` -> ### Why so much JSON? (A note on JSON API) ->The Terminal49 API is JSON API compliant, which means that there are nifty libraries which can translate JSON into a fully fledged object model that can be used with an ORM. This is very powerful, but it also requires a larger, more structured payload to power the framework. The tradeoff, therefore, is that it's less convenient if you're parsing the JSON directly. Ultimately we strongly recommend you set yourself up with a good library to use JSON API to its fullest extent. But for the purposes of understanding the API's fundamentals and getting your feet wet, we'll work with the data directly. +> ### Why so much JSON? (A note on JSON:API) +>The Terminal49 API is JSON:API compliant. JSON:API libraries can translate the response into a full object model compatible with an ORM, which is powerful but produces larger, more structured payloads. If you parse JSON directly, this can feel verbose. For production use, consider adopting a [JSON:API client library](https://jsonapi.org/implementations/#client-libraries) to get the most out of the format. For this tutorial, you will work with the data directly. ### What type of webhook event is this? @@ -162,7 +162,7 @@ When a tracking request has succeeded, the webhook event **includes** informatio In the payload below (again, truncated by ellipses for clarity) you'll see a list of JSON objects in the "included" section. Each object has a **type** and **attributes**. The type tells you what the object is. The attributes tell you the data that the object carries. -Some objects have **relationships**. These are simply links to another object. The most essential objects in relationships are often included, but objects that don't change very often, for example an object that describes a teminal, are not included - once you query these, you should consider caching them locally. +Some objects have **relationships** that link to other objects. The most essential related objects are included in the payload, but objects that rarely change (for example, a terminal) are not. Consider caching these locally after you query them. ```jsx "included":[ diff --git a/docs/api-docs/getting-started/start-here.mdx b/docs/api-docs/getting-started/start-here.mdx index 84ddc10..8be605d 100644 --- a/docs/api-docs/getting-started/start-here.mdx +++ b/docs/api-docs/getting-started/start-here.mdx @@ -11,11 +11,11 @@ keywords: - "Postman" - "track shipments" --- -So you want to start tracking your ocean shipments and containers and you have a few BL numbers. Follow the guide. +Ready to start tracking your ocean shipments and containers? Follow this guide to get up and running. -Our API responses use [JSONAPI](https://jsonapi.org/) schema. There are [client libraries](https://jsonapi.org/implementations/#client-libraries) available in almost every language. Our API should work with these libs out of the box. +The Terminal49 API uses [JSON:API](https://jsonapi.org/) schema. [Client libraries](https://jsonapi.org/implementations/#client-libraries) are available in almost every language and work with the API out of the box. -Our APIs can be used with any HTTP client; choose your favorite! We love Postman, it's a friendly graphical interface to a powerful cross-platform HTTP client. Best of all it has support for the OpenAPI specs that we publish with all our APIs. We have created a collection of requests for you to easily test the API endpoints with your API Key. Link to the collection below. +You can use any HTTP client to interact with the API. [Postman](https://www.postman.com/) is a good option — it provides a graphical interface and supports the OpenAPI specs published with the API. Use the collection below to test endpoints with your API key. **Run in Postman** @@ -23,7 +23,7 @@ Our APIs can be used with any HTTP client; choose your favorite! We love Postman *** ## Get an API key -Sign in to your Terminal49 account and go to your [developer portal](https://app.terminal49.com/developers/api-keys) page to get your API key. +Sign in to your Terminal49 account and go to the [developer portal](https://app.terminal49.com/developers/api-keys) to get your API key. ### Authentication When passing your API key it should be prefixed with `Token`. For example, if your API Key is 'ABC123' then your Authorization header would look like: diff --git a/docs/api-docs/getting-started/tracking-shipments-and-containers.mdx b/docs/api-docs/getting-started/tracking-shipments-and-containers.mdx index c5c7a9e..34cca73 100644 --- a/docs/api-docs/getting-started/tracking-shipments-and-containers.mdx +++ b/docs/api-docs/getting-started/tracking-shipments-and-containers.mdx @@ -46,27 +46,27 @@ You can see a complete list of supported SCACs in row 2 of the Carrier Data Matr ## How do I use tracking requests? -Terminal49 is an event-based API, which means that the API can be used asynchronously. In general the data flow is: +Terminal49 is an event-based API, which means you can use it asynchronously. The general data flow is: 1. You send a tracking request to the API with your Bill of Lading number and SCAC. - 2. The API will respond that it has successfully received your Tracking Request and return the Shipment's data that is available at that time. - 3. After you have submitted a tracking request, the shipment and all of the shipments containers are tracked automatically by Terminal49. - 4. You will be updated when anything changes or more data becomes available. Terminal49 sends updates relating to your shipment via posts to the webhook you have registered. Generally speaking, updates occur when containers reach milestones. ETA updates can happen at any time. As the ship approaches port, you will begin to receive Terminal Availability data, Last Free day, and so forth. - 5. At any time, you can directly request a list of shipments and containers from Terminal49, and the API will return current statuses and information. This is covered in a different guide. + 2. The API confirms it received your tracking request and returns the shipment data available at that time. + 3. After you submit a tracking request, Terminal49 automatically tracks the shipment and all of its containers. + 4. Terminal49 sends updates to the webhook you have registered whenever data changes. Updates typically occur when containers reach milestones. ETA updates can happen at any time. As the ship approaches port, you receive terminal availability data, Last Free Day, and more. + 5. You can request a list of shipments and containers from Terminal49 at any time. This is covered in a separate guide. -## How do you send me the data relating to the tracking request? +## How do you receive tracking request data? -You have two options. First, you can poll for updates. This is the way we'll show you first. +You have two options. First, you can poll for updates. -You can poll the `GET /tracking_request/{id}` endpoint to see the status of your request. You just need to track the ID of your tracking request, which is returned to you by the API. +Poll the `GET /tracking_request/{id}` endpoint to check the status of your request. You only need the tracking request ID, which the API returns when you create the request. -Second option is that you can register a webhook and the API will post updates when they happen. This is more efficient and therefore preferred. But it also requires some work to set up. +The second option is to register a webhook so the API posts updates as they happen. This is more efficient and the preferred approach, but it requires some setup. -A Webhook is another name for a web-based callback URL, or a HTTP Push API. Webhooks provide a method for an API to post a notification to your service. Specifically, a webhook is simply a URL that can receive HTTP Post Requests from the Terminal49 API. +A webhook is a callback URL that receives HTTP POST requests from the Terminal49 API whenever tracking data changes. -When we successfully lookup the Bill of Lading with the Carrier's SCAC, we will create a shipment, and send the event `tracking_request.succeeded` to your webhook endpoint with the associated record. +When the Bill of Lading and SCAC match successfully, Terminal49 creates a shipment and sends the `tracking_request.succeeded` event to your webhook endpoint with the associated record. -If we encounter a problem we'll send the event `tracking_request.failed`. +If there is a problem, Terminal49 sends the `tracking_request.failed` event. ![](/images/create-shipment-flow.png) @@ -76,11 +76,9 @@ If we encounter a problem we'll send the event `tracking_request.failed`. The API uses Bearer Token style authentication. This means you send your API Key as your token in every request. -To get your API token to Terminal49 and go to your [account API settings](https://app.terminal49.com/settings/api) +Sign in to Terminal49 and go to your [account API settings](https://app.terminal49.com/settings/api) to get your API token. -The token should be sent with each API request in the Authentication header: - -Support [dev@terminal49.com](mailto:dev@terminal49.com) +Send the token with each API request in the Authorization header: ``` Authorization: Token YOUR_API_KEY @@ -88,7 +86,7 @@ Authorization: Token YOUR_API_KEY ## How to create a tracking request -Here is javascript code that demonstates sending a tracking request +Here is JavaScript code that demonstrates sending a tracking request ```json fetch("https://api.terminal49.com/v2/tracking_requests", { @@ -168,9 +166,9 @@ Note that if you try to track the same shipment, you will receive an error like ``` -**Why so much JSON? (A note on JSON API)** +**Why so much JSON? (A note on JSON:API)** -The Terminal49 API is JSON API compliant, which means that there are nifty libraries which can translate JSON into a fully fledged object model that can be used with an ORM. This is very powerful, but it also requires a larger, more structured payload to power the framework. The tradeoff, therefore, is that it's less convenient if you're parsing the JSON directly. Ultimately we strongly recommend you set yourself up with a good library to use JSON API to its fullest extent. But for the purposes of understanding the API's fundamentals and getting your feet wet, we'll work with the data directly. +The Terminal49 API is JSON:API compliant. JSON:API libraries can translate the response into a full object model compatible with an ORM, which is powerful but produces larger, more structured payloads. If you parse JSON directly, this can feel verbose. For production use, consider adopting a [JSON:API client library](https://jsonapi.org/implementations/#client-libraries) to get the most out of the format. For this tutorial, you will work with the data directly. @@ -178,8 +176,8 @@ The Terminal49 API is JSON API compliant, which means that there are nifty libra Try it using the request maker below! - 1. Enter your API token in the autorization header value. - 2. Enter a value for the `request_number` and `scac`. The request number has to be a shipping line booking or master bill of lading number. The SCAC has to be a shipping line scac (see data sources to get a list of valid SCACs) + 1. Enter your API token in the authorization header value. + 2. Enter a value for the `request_number` and `scac`. The request number must be a shipping line booking or master bill of lading number. The SCAC must be a shipping line SCAC (see data sources for a list of valid SCACs). Note that you can also access sample code in multiple languages by clicking the "Code Generation" below. @@ -188,11 +186,11 @@ Note that you can also access sample code in multiple languages by clicking the The most common issue people encounter is that they are entering the wrong number. -Please check that you are entering the Bill of Lading number, booking number, or container number and not internal reference at your company or by your frieght forwarder. You can the number you are supplying by going to a carrier's website and using their tools to track your shipment using the request number. If this works, and if the SCAC is supported by T49, you should able to track it with us. +Check that you are entering a Bill of Lading number, booking number, or container number — not an internal reference from your company or freight forwarder. Verify the number by going to the carrier's website and tracking the shipment with it. If that works and the SCAC is supported by Terminal49, you should be able to track it through the API. -If you're unsure of the correct SCAC, try the [Auto-Detect Carrier](/api-docs/api-reference/tracking-requests/auto-detect-carrier) endpoint first. +If you are unsure of the correct SCAC, try the [Auto-Detect Carrier](/api-docs/api-reference/tracking-requests/auto-detect-carrier) endpoint first. -It is entirely possible that's neither us nor you but the shipping line is giving us a headache. Temporary network problems, not populated manifest and other things happen! You can read on how are we handling them in the [Tracking Request Retrying](/api-docs/useful-info/tracking-request-retrying) section. +Sometimes the issue is on the shipping line's side. Temporary network problems, unpopulated manifests, and other issues can occur. See the [Tracking Request Retrying](/api-docs/useful-info/tracking-request-retrying) section for how Terminal49 handles these cases. @@ -219,7 +217,7 @@ It is entirely possible that's neither us nor you but the shipping line is givin ## Try it: list your active tracking requests -We have not yet set up a webook to receive status updates from the Terminal49 API, so we will need to manually poll to check if the Tracking Request has succeeded or failed. +If you have not set up a webhook to receive status updates from the Terminal49 API, you need to poll manually to check whether the tracking request succeeded or failed. **Try it below. Click "Headers" and replace `` with your API key.** diff --git a/docs/api-docs/in-depth-guides/adding-customer.mdx b/docs/api-docs/in-depth-guides/adding-customer.mdx index dde05d4..4be0caa 100644 --- a/docs/api-docs/in-depth-guides/adding-customer.mdx +++ b/docs/api-docs/in-depth-guides/adding-customer.mdx @@ -10,18 +10,18 @@ keywords: - "party ID" - "tracking request" --- -## Why you would want to add a party to a tracking request? +## Why add a party to a tracking request? -Adding a party to a tracking request allows you to associate customer information with the tracking request. The customer added to the tracking request will be assigned to the shipment when it is created, just like reference numbers and tags. This can help in organizing and managing your shipments more effectively. +Adding a party to a tracking request associates customer information with the request. The customer is assigned to the shipment when it is created, just like reference numbers and tags. This helps you organize and manage your shipments more effectively. -## How to get the party ID? +## How to get the party ID You can either find an existing party or create a new one. - To find an existing party, jump to [Listing all parties](#listing-all-parties) section. - To create a new party, jump to [Adding party for a customer](#adding-party-for-a-customer) section. -## Listing all parties +## List all parties You can list all parties associated with your account through the [API](/api-docs/api-reference/parties/list-parties). @@ -61,9 +61,9 @@ Endpoint: **GET** - [https://api.terminal49.com/v2/parties](/api-docs/api-refere After you get all the parties you would filter the parties by `company_name` to find the correct ID, either by looking through the list manually or using code to automate the process. -## How to add party to tracking request if you have the party ID? +## Add a party to a tracking request -To add a customer to a tracking request, you need to add the party to the tracking request as a customer relationship while being created. **Note** that a party cannot be added to a tracking request that has already been created. +To add a customer to a tracking request, include the party as a customer relationship when creating the request. **Note:** you cannot add a party to a tracking request that has already been created. Endpoint: **POST** - [https://api.terminal49.com/v2/tracking_requests](/api-docs/api-reference/tracking-requests/create-a-tracking-request) @@ -134,9 +134,9 @@ After you send a **POST** request to create a tracking request, you will receive } ``` -## Adding party for a customer +## Create a party for a customer -For adding a customer to a tracking request, you need to create a party first. You can create a party through the [API](/api-docs/api-reference/parties/create-a-party). +To add a customer to a tracking request, you first need to create a party. You can create a party through the [API](/api-docs/api-reference/parties/create-a-party). Endpoint: **POST** - [https://api.terminal49.com/v2/parties](/api-docs/api-reference/parties/create-a-party) @@ -165,13 +165,13 @@ After you send a **POST** request to create a party, you will receive a response } ``` -## Editing a party +## Edit a party You can update existing parties through the [API](/api-docs/api-reference/parties/edit-a-party). Endpoint: **PATCH** - [https://api.terminal49.com/v2/parties/PARTY_ID](/api-docs/api-reference/parties/edit-a-party) -## Reading a party +## Read a party You can retrieve the details of an existing party through the [API](/api-docs/api-reference/parties/get-a-party). diff --git a/docs/api-docs/in-depth-guides/event-timestamps.mdx b/docs/api-docs/in-depth-guides/event-timestamps.mdx index 8cea4f6..d0e37c7 100644 --- a/docs/api-docs/in-depth-guides/event-timestamps.mdx +++ b/docs/api-docs/in-depth-guides/event-timestamps.mdx @@ -11,7 +11,7 @@ keywords: - "timezone conversion" - "IANA timezone" --- -Through the typical container lifecycle events occur across multiple timezones. Wheverever you see a timestamp for some kind of transporation event, there should be a corresponding [IANA tz](https://www.iana.org/time-zones). +Through the typical container lifecycle, events occur across multiple timezones. Wherever you see a timestamp for a transport event, there should be a corresponding [IANA timezone](https://www.iana.org/time-zones). Event timestamps are stored and returned in UTC. If you wish to present them in the local time you need to convert that UTC timestamp using the corresponding timezone. @@ -26,9 +26,9 @@ then the local time of the `pod_arrived_at` timestamp would be `2022-12-21T23:00 ## When the corresponding timezone is null -When there is event that occurs where Terminal49 cannot determine the location (and therefore the timezone) of the event the system is unable to store the event in true UTC. +When an event occurs and Terminal49 cannot determine the location (and therefore the timezone), the system cannot store the event in true UTC. -In this scenario we take timestamp as given from the source and parse it in UTC. +In this scenario, Terminal49 takes the timestamp as given from the source and parses it in UTC. ### Example ``` diff --git a/docs/api-docs/in-depth-guides/quickstart.mdx b/docs/api-docs/in-depth-guides/quickstart.mdx index 23ba6e8..1302289 100644 --- a/docs/api-docs/in-depth-guides/quickstart.mdx +++ b/docs/api-docs/in-depth-guides/quickstart.mdx @@ -14,7 +14,7 @@ keywords: --- ## Before you begin -You'll need a four things to get started. +You need four things to get started. 1. **A Bill of Lading (BOL) number.** This is issued by your carrier. BOL numbers are found on your [bill of lading](https://en.wikipedia.org/wiki/Bill_of_lading) document. Ideally, this will be a shipment that is currently on the water or in terminal, but this is not necessary. 2. **The SCAC of the carrier that issued your bill of lading.** The Standard Carrier Alpha Code of your carrier is used to identify carriers in computer systems and in shipping documents. You can learn more about these [here](https://en.wikipedia.org/wiki/Standard_Carrier_Alpha_Code). @@ -50,15 +50,15 @@ Note that you can also access sample code, include a cURL template, by clicking ## Check your tracking request succeeded -We have not yet set up a webook to receive status updates from the Terminal49 API, so we will need to manually poll to check if the Tracking Request has succeeded or failed. +If you have not set up a webhook to receive status updates from the Terminal49 API, you need to poll manually to check whether the tracking request succeeded or failed. -> ### Tracking Request Troubleshooting +> ### Tracking request troubleshooting > -> The most common issue people encounter is that they are entering the wrong number. +> The most common issue is entering the wrong number. > -> Please check that you are entering the Bill of Lading number, booking number, or container number and not internal reference at your company or by your frieght forwarder. You can the number you are supplying by going to a carrier's website and using their tools to track your shipment using the request number. If this works, and if the SCAC is supported by T49, you should able to track it with us. +> Check that you are entering a Bill of Lading number, booking number, or container number — not an internal reference from your company or freight forwarder. Verify the number by going to the carrier's website and tracking the shipment with it. If that works and the SCAC is supported by Terminal49, you should be able to track it through the API. > -> You can always email us at support@terminal49.com if you have persistent issues. +> Email support@terminal49.com if you have persistent issues. ** Try it below. Click "Headers" and replace `` with your API key.** @@ -113,9 +113,9 @@ Try it after replacing `` with your API key. ## Listening for updates with webhooks -The true power of Terminal49's API is that it is asynchronous. You can register a Webhook, which is essentially a callback URL that our systems HTTP Post to when there are updates. +The real power of Terminal49's API is that it is asynchronous. You can register a webhook — a callback URL that Terminal49 sends HTTP POST requests to when updates occur. -To try this, you will need to first set up a URL on the open web to receive POST requests. Once you have done this, you'll be able to receive status updates from containers and shipments as they happen, which means you don't need to poll us for updates; we'll notify you. +To try this, first set up a URL on the open web to receive POST requests. Once configured, you receive status updates from containers and shipments as they happen, so you do not need to poll for updates. ** Try it below. Click "Headers" and replace YOUR_API_KEY with your API key.** diff --git a/docs/api-docs/in-depth-guides/rail-integration-guide.mdx b/docs/api-docs/in-depth-guides/rail-integration-guide.mdx index 279cb1a..6827ade 100644 --- a/docs/api-docs/in-depth-guides/rail-integration-guide.mdx +++ b/docs/api-docs/in-depth-guides/rail-integration-guide.mdx @@ -46,11 +46,11 @@ By integrating with these carriers, Terminal49 ensures that you have direct acce Terminal49 seamlessly tracks your containers as they go from container ship, to ocean terminal, to rail carrier. -We provide a [set of Transport Events](#webhook-notifications) that let you track the status of your containers as they move through the rail system. You can be notified by webhook whenever these events occur. +Terminal49 provides a [set of transport events](#webhook-notifications) that let you track the status of your containers as they move through the rail system. You can receive webhook notifications whenever these events occur. -We also provide a set of attributes [on the container model](/api-docs/api-reference/containers/get-a-container) that let you know the current status of your container at any given time, as well as useful information such as ETA, pickup facility, and availability information. For details on hold types, fee types, and how to determine release readiness at the port or an inland destination, see [Container Holds, Fees, and Release Readiness](/api-docs/in-depth-guides/holds-and-fees). +Terminal49 also provides a set of attributes [on the container model](/api-docs/api-reference/containers/get-a-container) with the current status of your container at any given time, including ETA, pickup facility, and availability information. For details on hold types, fee types, and how to determine release readiness at the port or an inland destination, see [Container Holds, Fees, and Release Readiness](/api-docs/in-depth-guides/holds-and-fees). -### Rail-Specific Transport Events +### Rail-specific transport events There are several core Transport Events that occur on most rail journeys. Some rail carriers do not share all events, but in general these are the key events for a container. @@ -123,7 +123,7 @@ There's also a set of events that are triggered when the status of the container | Full Out | `container.transport.full_out` | The full container leaves the rail terminal. | Example | | Empty In | `container.transport.empty_in` | The empty container is returned to the terminal. | Example | -Finally, we have a webhook notifications for when the destination ETA changes. +Finally, there is a webhook notification for when the destination ETA changes. | Transport Event | Webhook Notification | Description | Example | |----------------|----------------------|-------------|---------| diff --git a/docs/api-docs/in-depth-guides/rate-limiting.mdx b/docs/api-docs/in-depth-guides/rate-limiting.mdx index 571a40f..b48f8d6 100644 --- a/docs/api-docs/in-depth-guides/rate-limiting.mdx +++ b/docs/api-docs/in-depth-guides/rate-limiting.mdx @@ -84,7 +84,7 @@ If your use case requires a higher rate limit: 3. **Provide details** about your use case and expected request volume 4. **Our team will work with you** to find an appropriate solution -## Example: Handling Rate Limits +## Example: handling rate limits Here's an example of how to properly handle rate limit responses in Python: diff --git a/docs/api-docs/in-depth-guides/terminal49-map.mdx b/docs/api-docs/in-depth-guides/terminal49-map.mdx index 8ac7a13..7358bd2 100644 --- a/docs/api-docs/in-depth-guides/terminal49-map.mdx +++ b/docs/api-docs/in-depth-guides/terminal49-map.mdx @@ -130,7 +130,7 @@ const map = new window.TntMap(element, { ### Styling the map All of the map styles are written as human-readable CSS classes and variables. -You can used those to customize the map to your liking. +You can use these to customize the map to your liking. The styles are written in [BEM](https://getbem.com/) style as well as they're scoped under a `.tntm` class to avoid style conflicts with your website. #### Sizing @@ -192,7 +192,7 @@ Result: ![terminal49-map-colors.png](/images/terminal49-map-colors.png) -It's also possible to change the marker colors based on wheter they're hovered over or not. +You can also change the marker colors based on whether they are hovered over or not. This is what we do on the Terminal49 website to style the map markers to our needs: diff --git a/docs/api-docs/in-depth-guides/terminal49-widget.mdx b/docs/api-docs/in-depth-guides/terminal49-widget.mdx index 94af34c..49e7180 100644 --- a/docs/api-docs/in-depth-guides/terminal49-widget.mdx +++ b/docs/api-docs/in-depth-guides/terminal49-widget.mdx @@ -14,12 +14,12 @@ keywords: ### How do I embed the widget on my website? -> First, you neeed a publishable API KEY. You can get this by reaching out to us at support@terminal49.com +> First, you need a publishable API key. You can get one by contacting support@terminal49.com Once you have the key, you can embed the widget on your website. We suggest creating a dedicated page for tracking, typically at `company-website.com/track`. You can also embed the widget directly on your homepage. If you decide to create a dedicated tracking page, we recommend adding a `h1` tag above the script. Feel free to customize the `h1` contents in the script. -Copy and pase the code below and insert it on top of the page (under your page navigation if you a horizontal top navigation). Replace `REPLACE_WITH_PUBLISHABLE_KEY` with the `API KEY` you receive from us. We suggest adding a `h1` tag above the script. Feel free to remove change the `h1` contents in the script below. +Copy and paste the code below and insert it at the top of the page (under your navigation if you have a horizontal top navigation). Replace `REPLACE_WITH_PUBLISHABLE_KEY` with the API key you receive. You can customize the `h1` contents in the script below. To query a bill of lading, container, or reference number, simply replace `REPLACE_WITH_NUMBER_TO_QUERY` with the specific number you want to search for. If `data-number` exists, the query will be performed only once. @@ -39,13 +39,13 @@ To query a bill of lading, container, or reference number, simply replace `REPLA With a few lines of code, you can embed an interactive container tracking form. Once the widget is live on your website, your customer can enter a master bill of lading, container number, or reference numbers that a shipment is tagged with. After the number has been entered, the widget will retrieve and display shipment and container details from your Terminal49 account. ### Do I need Terminal49 account? -Yes, the information that fetched and displayed by the widget is based on the shipments and containers tracked within your Terminal49 account. +Yes. The information fetched and displayed by the widget is based on the shipments and containers tracked within your Terminal49 account. ### Can my customer track *any* shipment/container? No, only the shipments and containers that are tracked in your Terminal49 account. ### Is there a cost to embed the widget? -Yes, there is a $500/month fee to embed and use the widget. This include unlimited number of visitors and tracking requests. +Yes, there is a $500/month fee to embed and use the widget. This includes an unlimited number of visitors and tracking requests. ## Terminal49 container tracking widget one-pager diff --git a/docs/api-docs/in-depth-guides/tracking-request-lifecycle.mdx b/docs/api-docs/in-depth-guides/tracking-request-lifecycle.mdx index d3c3709..f7e0c98 100644 --- a/docs/api-docs/in-depth-guides/tracking-request-lifecycle.mdx +++ b/docs/api-docs/in-depth-guides/tracking-request-lifecycle.mdx @@ -11,19 +11,19 @@ keywords: - "retry logic" - "failed tracking request" --- -When you submit a tracking request your request is added to our queue to being checked at the shipping line. So what happens if the request doesn't go through correctly? +When you submit a tracking request, your request is added to a queue to be checked with the shipping line. What happens if the request does not go through correctly? -If we are having difficulty connecting to the shipping line, or if we are unable to parse the response from the shipping line, we will keep retrying up to 14 times. +If Terminal49 has difficulty connecting to the shipping line or cannot parse the response, it retries up to 14 times. This process can take up to approximately 24 hours. You will not receive a `tracking_request.failed` webhook notification until we have exhausted the retries, and the `status` field will not be changed to `failed` until then. ## Request number not found / awaiting manifest -If the shipping line returns a response that it cannot find the provided number we either immediately fail the tracking request or keep trying depending on whether the `request_type` is a container or not: +If the shipping line returns a response that it cannot find the provided number, Terminal49 either immediately fails the tracking request or keeps trying, depending on the `request_type`: - **Containers** fail straight away after a not found response from the shipping line. -- **Bill of lading** and **booking numbers** do not fail instantly. We change the `status` to `awaiting_manifest` and will keep checking your request daily. You will receive a `tracking_request.awaiting_manifest` webhook notification the first time it happens. If your request number cannot be found after 7 days we will mark the tracking request as failed by changing the `status` field `failed` and sending the `tracking_request.failed` event to your webhook. -- Should you wish to adjust the duration before marking your tracking requests as failed, please contact us through support@terminal49.com. +- **Bill of lading** and **booking numbers** do not fail instantly. The `status` changes to `awaiting_manifest` and Terminal49 keeps checking your request daily. You receive a `tracking_request.awaiting_manifest` webhook notification the first time this happens. If the request number cannot be found after 7 days, the tracking request is marked as failed with the `status` set to `failed` and the `tracking_request.failed` event sent to your webhook. +- To adjust the duration before marking tracking requests as failed, contact support@terminal49.com. - **Incorrect request number type** if the request number type (ex. booking number) is incorrect, the tracking request will still fail even though the request number is correct. @@ -41,14 +41,14 @@ The `failed_reason` field can take one of the following temporary values: - `unrecognized_response` when we could not parse the response from the shipping line, - `shipping_line_unreachable` if the shipping line was unreachable, - `internal_processing_error` when we faced other issue, -- `awaiting_manifest` if the shipping line indidicates a bill of lading number is found, but data is not yet available, or if the requested number could not be found. +- `awaiting_manifest` if the shipping line indicates a bill of lading number is found but data is not yet available, or if the requested number could not be found. ### Permanent reasons Temporary reasons can become permanent when the `status` changes to `failed`: - `duplicate` when the shipment already existed, -- `expired` when the tracking request was created more than 7 days ago and still not succeded, +- `expired` when the tracking request was created more than 7 days ago and still has not succeeded, - `retries_exhausted` if we tried for 14 times to no avail, - `not_found` if the shipping line could not find the BL number. - `invalid_number` if the shipping line rejects the formatting of the number. @@ -68,7 +68,7 @@ Terminal49 will stop tracking requests for the following reasons: - The booking was cancelled. - The data is no longer available at the shipping line. - All shipment containers are marked `empty_returned`. -- More than 56 days have passed since the shipment arrived at it's destination. +- More than 56 days have passed since the shipment arrived at its destination. - There have been no updates from the shipping line for more than 56 days. In addition end-users may stop tracking a shipment through the dashboard. diff --git a/docs/api-docs/in-depth-guides/webhooks.mdx b/docs/api-docs/in-depth-guides/webhooks.mdx index 3839705..01ca6ea 100644 --- a/docs/api-docs/in-depth-guides/webhooks.mdx +++ b/docs/api-docs/in-depth-guides/webhooks.mdx @@ -69,9 +69,9 @@ Event | Description When an event is triggered we will attempt to post to the URL you provided with the webhook. -The payload of every webhook is a `webhook_notification`. Each Webhook notification includes a `reference_object` in it's relationships which is the subject of that notification (e.g. a tracking request, or an updated container). +The payload of every webhook is a `webhook_notification`. Each webhook notification includes a `reference_object` in its relationships, which is the subject of that notification (e.g., a tracking request or an updated container). -Please note that we expect the endpoint to return [HTTP 200 OK](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200), [HTTP 201](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201), [HTTP 202](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202) or [HTTP 204](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204). We aim to deliver all webhook notifications, so any other response, including timeout, will result in a dozen of retries. +Your endpoint must return [HTTP 200 OK](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200), [HTTP 201](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201), [HTTP 202](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202), or [HTTP 204](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204). Any other response, including a timeout, triggers retries (up to a dozen attempts). ```json json_schema { @@ -267,7 +267,7 @@ end The container updated event lets you know about changes to container properties at the terminal, or which terminal the container is (or will be) located at. -The `changeset` attribute on is a hash of all the properties which changed on the container. +The `changeset` attribute is a hash of all the properties that changed on the container. Each changed property is the hash key. The prior value is the first item in the array, and the current value is the second item in the array. diff --git a/docs/api-docs/useful-info/tracking-request-retrying.mdx b/docs/api-docs/useful-info/tracking-request-retrying.mdx index de36368..2902092 100644 --- a/docs/api-docs/useful-info/tracking-request-retrying.mdx +++ b/docs/api-docs/useful-info/tracking-request-retrying.mdx @@ -10,10 +10,10 @@ keywords: - "awaiting_manifest" - "request status" --- -When you submit a tracking request your request is added to our queue to being checked at the shipping line. So what happens if the request doesn't go through correctly? +When you submit a tracking request, your request is added to a queue to be checked with the shipping line. What happens if the request does not go through correctly? -If we are having difficulty connecting to the shipping line, or if we are unable to parse the response from the shipping line, we will keep retrying up to 14 times with an exponential back off. This process can take up to approximately 24 hours. You will not receive a `tracking_request.failed` webhook notification until we have exhausted the retries. +If Terminal49 has difficulty connecting to the shipping line or cannot parse the response, it retries up to 14 times with exponential backoff. This process can take up to approximately 24 hours. You do not receive a `tracking_request.failed` webhook notification until all retries are exhausted. -If the shipping line returns a response that it cannot find the provided number then we will immediately return the `tracking_request.failed` event to your webhook. +If the shipping line returns a response that it cannot find the provided number, Terminal49 immediately sends the `tracking_request.failed` event to your webhook. -If you want to see the status of your tracking request you can make a [GET request](/api-docs/api-reference/tracking-requests/get-a-single-tracking-request) on it's `id` to see how many times it has retried, and what the most recent failure reason was. \ No newline at end of file +To check the status of your tracking request, make a [GET request](/api-docs/api-reference/tracking-requests/get-a-single-tracking-request) using its `id` to see how many times it has retried and what the most recent failure reason was. \ No newline at end of file