### List Air Shipments - Example Query 1 (Status and Airline Filter) Source: https://api.shipsgo.com/docs/v2/specs/postman-collection This example demonstrates how to list air shipments that are currently 'EN_ROUTE' and carried by specific airlines ('TK' or 'LH'). It also sorts the results by the 'date_of_rcf' in ascending order. This query is used with the GET /air/shipments endpoint. ```plaintext /air/shipments ?filters[status]=eq:EN_ROUTE &filters[airline]=in:TK,LH &order_by=date_of_rcf,asc ``` -------------------------------- ### List Air Shipments - Example Query 2 (Destination and Date Filter) Source: https://api.shipsgo.com/docs/v2/specs/postman-collection This example shows how to retrieve air shipments destined for India ('IN') that were dispatched between September 1, 2024, and October 1, 2024. The results are ordered by the departure date in ascending order. This query is used with the GET /air/shipments endpoint. ```plaintext /air/shipments ?filters[destination_country]=eq:IN &filters[date_of_dep]=between:2024-09-01...2024-10-01 &order_by=date_of_dep,asc ``` -------------------------------- ### Get Air Airlines List (cURL) Source: https://api.shipsgo.com/docs/v2/index Example cURL command to fetch a list of air airlines. Requires an 'X-Shipsgo-User-Token' for authentication. Supports filtering and ordering via query parameters. ```cURL curl -X GET "https://api.shipsgo.com/v2/air/airlines?filters=&order_by=&skip=&take=" \ -H "X-Shipsgo-User-Token: " \ -H "Accept: */*" ``` -------------------------------- ### Shipment Creator Information Example Source: https://api.shipsgo.com/docs/v2/specs/openapi Details the creator of the shipment, including their full name and email address. This field is useful for internal tracking and communication. ```json { "creator": { "name": "John Doe", "email": "john.doe@example.com" } } ``` -------------------------------- ### Tracking Token Generation Example Source: https://api.shipsgo.com/docs/v2/specs/openapi Shows how to use the 'map' token to create a public URL for viewing shipment details and its current location on the Shipsgo Map. This requires the shipment ID and the provided map token. ```text https://map.shipsgo.com/air/shipments/{shipment_id}?token={map_token} ``` -------------------------------- ### Shipment Route Example Source: https://api.shipsgo.com/docs/v2/specs/openapi Provides details about the shipment's journey, including origin and destination airports, departure and arrival times, and transit duration. It also includes transshipment count and transit completion percentage. ```json { "route": { "origin": { "location": { "iata_code": "LAX", "name": "Los Angeles International Airport", "city": "Los Angeles", "country": "USA" }, "date_of_dep": "2023-10-26T14:30:00Z", "date_of_dep_initial": "2023-10-26T14:30:00Z" }, "ts_count": 0, "destination": { "location": { "iata_code": "JFK", "name": "John F. Kennedy International Airport", "city": "New York", "country": "USA" }, "date_of_rcf": "2023-10-27T08:00:00Z", "date_of_rcf_initial": "2023-10-27T08:00:00Z" }, "transit_time": 18, "transit_percentage": 100 } } ``` -------------------------------- ### Shipment Status Enum Example Source: https://api.shipsgo.com/docs/v2/specs/openapi Illustrates the possible status values for a shipment. These statuses indicate the current stage of the shipment, from initial loading to final delivery or if it's untracked. ```json { "status": "LOADED" } ``` -------------------------------- ### GET /websites/api_shipsgo_v2/shipments Source: https://api.shipsgo.com/docs/v2/specs/openapi Retrieves a list of shipments based on specified query parameters. Supports filtering by date, sorting, and pagination. ```APIDOC ## GET /websites/api_shipsgo_v2/shipments ### Description Retrieves a list of shipments with support for filtering by various date fields (created, updated, checked, discarded), sorting by specified fields, and pagination using skip and take parameters. ### Method GET ### Endpoint `/websites/api_shipsgo_v2/shipments` ### Parameters #### Query Parameters - **created_at** (string) - Optional - Filter by creation date. Accepts `eq`, `gt`, `gte`, `lt`, `lte`, `between` operators. - **updated_at** (string) - Optional - Filter by update date. Accepts `eq`, `gt`, `gte`, `lt`, `lte`, `between` operators. - **checked_at** (string) - Optional - Filter by last check date. Accepts `eq`, `gt`, `gte`, `lt`, `lte`, `between` operators. - **discarded_at** (string) - Optional - Filter by discard date. Accepts `eq`, `gt`, `gte`, `lt`, `lte`, `between` operators. - **order_by** (string) - Optional - Sorts the list. Format: `field,direction` (e.g., `id,asc`). Default: `created_at,desc`. Available fields: `id`, `status`, `airline`, `date_of_dep`, `date_of_rcf`, `created_at`, `updated_at`, `checked_at`. - **skip** (integer) - Optional - The number of records to skip. Default: 0. - **take** (integer) - Optional - The number of records to return. Default: 25. Maximum: 100. **Note:** For date fields, you can specify a timezone; if none is provided, UTC is assumed. ### Request Example ``` GET /websites/api_shipsgo_v2/shipments?created_at=gt,2024-01-01T00:00:00Z&order_by=updated_at,desc&take=10 ``` ### Response #### Success Response (200) - **message** (string) - A message indicating the result (e.g., "SUCCESS"). - **shipments** (array) - A list of shipment objects. - **id** (integer) - Unique identifier for the shipment. - **reference** (string) - Internal unique identifier for the shipment. - **awb_number** (string) - Air Waybill number. - **airline** (object) - Information about the airline. - **iata** (string) - IATA code of the airline. - **name** (string) - Name of the airline. - **cargo** (object) - Cargo details. - **pieces** (integer) - Number of pieces. - **weight** (number) - Total weight. - **volume** (number) - Total volume. - **status** (string) - Current status of the shipment. - **status_split** (boolean) - Indicates if the status is split. - **route** (object) - Shipment route details. - **origin** (object) - Origin details. - **location** (object) - Origin location details. - **iata** (string) - IATA code of the origin location. - **name** (string) - Name of the origin location. - **timezone** (string) - Timezone of the origin location. - **country** (object) - Country details. - **code** (string) - ISO 3166-1 alpha-2 country code. - **name** (string) - Name of the country. - **date_of_dep** (string) - Departure date and time in ISO 8601 format. - **date_of_dep_initial** (string) - Initial departure date and time in ISO 8601 format. - **ts_count** (integer) - Number of transit stops. - **destination** (object) - Destination details. - **location** (object) - Destination location details. - **iata** (string) - IATA code of the destination location. - **name** (string) - Name of the destination location. - **timezone** (string) - Timezone of the destination location. - **country** (object) - Country details. - **code** (string) - ISO 3166-1 alpha-2 country code. - **name** (string) - Name of the country. - **date_of_rcf** (string) - Received from flight date and time in ISO 8601 format. - **date_of_rcf_initial** (string) - Initial received from flight date and time in ISO 8601 format. - **transit_time** (integer) - Transit time in hours. - **transit_percentage** (integer) - Percentage of transit completed. - **tags** (array) - List of tags associated with the shipment. - **id** (integer) - Tag ID. - **name** (string) - Tag name. - **creator** (object) - Information about the user who created the shipment record. - **name** (string) - Name of the creator. - **email** (string) - Email of the creator. - **created_at** (string) - Date and time the shipment was created. - **updated_at** (string) - Date and time the shipment was last updated. - **checked_at** (string) - Date and time the shipment was last checked. - **discarded_at** (string | null) - Date and time the shipment was discarded. - **meta** (object) - Meta information about the returned list. - **more** (boolean) - Indicates whether there are more resources to fetch. - **total** (integer | null) - Total number of resources (available when `more` is false). #### Response Example ```json { "message": "SUCCESS", "shipments": [ { "id": 1001, "reference": "INTERNAL_UNIQUE_IDENTIFIER", "awb_number": "624-88888888", "airline": {"iata": "PC", "name": "PEGASUS CARGO"}, "cargo": {"pieces": 33, "weight": 161.7, "volume": 1.13}, "status": "EN_ROUTE", "status_split": false, "route": { "origin": {"location": {"iata": "IST", "name": "Istanbul Airport", "timezone": "Europe/Istanbul", "country": {"code": "TR", "name": "Turkey"}}, "date_of_dep": "2024-09-22T17:13:15+03:00", "date_of_dep_initial": "2024-09-21T17:13:15+03:00"}, "ts_count": 1, "destination": {"location": {"iata": "HKG", "name": "Hong Kong International Airport", "timezone": "Asia/Hong_Kong", "country": {"code": "HK", "name": "Hong Kong"}}, "date_of_rcf": "2024-09-23T20:17:15+08:00", "date_of_rcf_initial": "2024-09-22T20:17:15+08:00"}, "transit_time": 22, "transit_percentage": 99 }, "tags": [{"id": 1001, "name": "IMPORT"}, {"id": 1002, "name": "CUSTOMER_ABC"}], "creator": {"name": "John Doe", "email": "john-doe@example.com"}, "created_at": "2024-09-23 07:42:15", "updated_at": "2024-09-23 07:42:15", "checked_at": "2024-09-23 07:42:15", "discarded_at": null } ], "meta": {"more": false, "total": 3} } ``` ``` -------------------------------- ### Shipment Details with Container Movements (Another Example) Source: https://api.shipsgo.com/docs/v2/specs/openapi Provides comprehensive details for a shipment, including port information, dates, and container specifics. Each container object contains its movement history, detailing events like loading, departure, arrival, and discharge with associated timestamps, locations, vessel names, and voyage numbers. This is useful for tracking individual container journeys within a shipment. ```json { "Active": { "value": { "message": "SUCCESS", "shipment": { "id": 1003, "reference": null, "booking_number": "OOLU4099552175", "container_number": "OOCU4935001", "container_count": 1, "carrier": { "scac": "OOLU", "name": "OOCL" }, "status": "DISCHARGED", "route": { "port_of_loading": { "location": { "code": "BRSSZ", "name": "SANTOS", "timezone": "America/Sao_Paulo", "country": { "code": "BR", "name": "Brazil" } }, "date_of_loading": "2025-03-10T12:00:00-03:00", "date_of_loading_initial": "2025-03-10T12:00:00-03:00" }, "ts_count": 1, "port_of_discharge": { "location": { "code": "CNSHA", "name": "SHANGHAI", "timezone": "Asia/Shanghai", "country": { "code": "CN", "name": "China" } }, "date_of_discharge": "2025-04-24T12:00:00+08:00", "date_of_discharge_initial": "2025-04-24T12:00:00+08:00" }, "transit_time": 45, "transit_percentage": 100, "co2_emission": null }, "containers": [ { "number": "OOCU4935001", "status": "EMPTY_RETURN", "size": 20, "type": "High Cube", "movements": [ { "event": "EMSH", "status": "ACT", "location": { "code": "BRSSZ", "name": "SANTOS", "timezone": "America/Sao_Paulo", "country": { "code": "BR", "name": "Brazil" } }, "vessel": null, "voyage": null, "timestamp": "2025-03-06T12:00:00-03:00" }, { "event": "GTIN", "status": "ACT", "location": { "code": "BRSSZ", "name": "SANTOS", "timezone": "America/Sao_Paulo", "country": { "code": "BR", "name": "Brazil" } }, "vessel": null, "voyage": null, "timestamp": "2025-03-06T12:00:00-03:00" } ] } ] } } } } ``` -------------------------------- ### GET /airlines Source: https://api.shipsgo.com/docs/v2/specs/openapi Retrieves a list of airlines supported by the Shipsgo platform. The response includes details such as IATA code, name, status, and associated prefixes for each airline. ```APIDOC ## GET /airlines ### Description Retrieves a list of supported airlines, including their IATA codes, names, operational status, and airline prefixes. ### Method GET ### Endpoint /airlines ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number for pagination. - **limit** (integer) - Optional - Number of results per page. ### Response #### Success Response (200) - **message** (string) - A message indicating the result (`SUCCESS`). - **airlines** (array) - A list of airline objects. - **iata** (string) - The IATA code for the airline. - **name** (string) - The name of the airline. - **status** (string) - The operational status of the airline (e.g., "ACTIVE"). - **prefixes** (array of strings) - A list of numeric prefixes associated with the airline. - **meta** (object) - Metadata for pagination. - **more** (boolean) - Indicates whether there are more resources to fetch. - **total** (integer, nullable) - The total number of resources available (only when `more` is false). #### Response Example ```json { "message": "SUCCESS", "airlines": [ { "iata": "AC", "name": "AIR CANADA", "status": "ACTIVE", "prefixes": [ "014" ] }, { "iata": "AF", "name": "AIR FRANCE", "status": "ACTIVE", "prefixes": [ "074", "057", "129" ] } ], "meta": { "more": true, "total": null } } ``` ``` -------------------------------- ### Ocean Shipments List Response Source: https://api.shipsgo.com/docs/v2/specs/postman-collection Example JSON response for the 'OCEAN - List of Shipments' endpoint, detailing shipment information including IDs, booking numbers, carrier details, route information, and creation timestamps. ```json { "message": "SUCCESS", "shipments": [ { "id": 7257, "reference": "string", "booking_number": "string", "container_number": "string", "container_count": 7668, "carrier": { "scac": "string", "name": "string" }, "status": "BOOKED", "route": { "port_of_loading": { "location": { "code": "string", "name": "string", "timezone": "string", "country": { "code": "string", "name": "string" } }, "date_of_loading": "1995-08-17", "date_of_loading_initial": "2018-03-22" }, "ts_count": 3034, "port_of_discharge": { "location": { "code": "string", "name": "string", "timezone": "string", "country": { "code": "string", "name": "string" } }, "date_of_discharge": "1983-12-14", "date_of_discharge_initial": "1977-10-21" }, "transit_time": 4048, "transit_percentage": 7597, "co2_emission": 6944.867831930963 }, "tokens": { "map": "656235a1-280f-81f7-7675-6a9899eecd10", "key_0": "string" }, "creator": { "name": "string", "email": "string" }, "tags": [ { "id": 1001, "name": "IMPORT" }, { "id": 1001, "name": "IMPORT" } ], "created_at": "string", "updated_at": "string", "checked_at": "string", "discarded_at": "string" } ] } ``` -------------------------------- ### Extended Shipment Status by Pieces Example Source: https://api.shipsgo.com/docs/v2/specs/openapi Demonstrates how to represent shipment status when dealing with split cargo. This field breaks down the status by the number of pieces, useful for tracking individual components of a multi-piece shipment. ```json { "status_extended": { "EN_ROUTE": 5 } } ``` ```json { "status_extended": { "EN_ROUTE": 3, "LANDED": 2 } } ``` -------------------------------- ### Shipment Creation Success Response (200 OK) Source: https://api.shipsgo.com/docs/v2/specs/postman-collection This is a successful response from the shipment creation API endpoint. It confirms that the shipment was created and tracking has started, returning a success message and the newly created shipment's ID and reference details. ```json { "message": "SUCCESS", "shipment": { "id": 123456, "reference": "INTERNAL_UNIQUE_IDENTIFIER", "container_number": "MSCU1234567", "booking_number": "MEDUQY000000" } } ``` -------------------------------- ### List Ocean Shipments with Filters Source: https://api.shipsgo.com/docs/v2/specs/openapi This endpoint retrieves a list of ocean shipments with options for filtering and sorting. Filters can be applied to various fields like status, carrier, country of loading, and dates. For example, you can filter for ongoing shipments by specific carriers or shipments loaded within a date range from a particular country. The `filters` parameter uses a `deepObject` style for structured queries. ```http GET /ocean/shipments?filters[status]=eq:SAILING&filters[carrier]=in:MSCU,OOLU&order_by=date_of_discharge,asc ``` ```http GET /ocean/shipments?filters[port_of_loading_country]=eq:IN&filters[date_of_loading]=between:2024-09-01...2024-10-01&order_by=date_of_loading,asc ``` ```http GET /ocean/shipments?filters[tags]=with:COMPANY_ABC&filters[creator]=eq:john-doe@example.com ``` -------------------------------- ### GET /ocean/carriers Source: https://api.shipsgo.com/docs/v2/specs/openapi Retrieves a list of ocean carriers with filtering and sorting options. ```APIDOC ## GET /ocean/carriers ### Description Retrieves a list of ocean carriers. Supports filtering by code, name, and status, and sorting by specified fields. **Example #1:** To filter the trackable carriers. ```plain /ocean/carriers?filters[status]=eq:ACTIVE ``` **Example #2:** To filter carriers that contain `CMA` in their name. ```plain /ocean/carriers?filters[name]=contains:CMA ``` ### Method GET ### Endpoint `/ocean/carriers` ### Parameters #### Query Parameters - **filters** (object) - Optional - Filter criteria for the carriers. Common structure is `filters[field]=operator:value(s)`. - **Field `code`**: Operators: `eq`. Description: The SCAC code of the carrier. Ex: `OOLU`, `MSCU`, `SG_TFEG`. - **Field `name`**: Operators: `eq`, `contains`, `not_contains`. Description: The name of the carrier. - **Field `status`**: Operators: `eq`. Description: Enum: `ACTIVE`, `PASSIVE`. - **order_by** (string) - Optional - Field to sort the list by. Common structure is `order_by` (followed by the field name). ### Response #### Success Response (200) - **carriers** (array) - An array of carrier objects. - **code** (string) - The SCAC code of the carrier. - **name** (string) - The name of the carrier. - **status** (string) - The status of the carrier (`ACTIVE` or `PASSIVE`). #### Response Example ```json { "carriers": [ { "code": "MSCU", "name": "Maersk Line", "status": "ACTIVE" }, { "code": "CMAU", "name": "CMA CGM", "status": "ACTIVE" } ] } ``` ``` -------------------------------- ### GET /ocean/carriers Source: https://api.shipsgo.com/docs/v2/specs/postman-collection Retrieves a list of ocean carriers. This endpoint supports filtering by carrier status and name, as well as sorting and pagination. ```APIDOC ## GET /ocean/carriers ### Description Retrieves a list of ocean carriers. This includes options to apply various filters and sorting. ### Method GET ### Endpoint /ocean/carriers ### Parameters #### Path Parameters None #### Query Parameters - **order_by** (string) - Optional - Specifies the order for the results. - **skip** (integer) - Optional - The number of results to skip. - **take** (integer) - Optional - The maximum number of results to return. - **filters[status]** (string) - Optional - Filters carriers by their status (e.g., `eq:ACTIVE`). - **filters[name]** (string) - Optional - Filters carriers whose name contains the specified string (e.g., `contains:CMA`). #### Request Body None ### Request Example ```json { "request": "GET /ocean/carriers?filters[status]=eq:ACTIVE" } ``` ### Response #### Success Response (200) - **message** (string) - A confirmation message. - **carriers** (array) - An array of carrier objects. - **scac** (string) - The SCAC code of the carrier. - **name** (string) - The name of the carrier. - **status** (string) - The status of the carrier (e.g., "PASSIVE"). - **meta** (object) - Metadata about the results. - **more** (boolean) - Indicates if there are more results available. - **total** (integer) - The total number of carriers. #### Response Example ```json { "message": "List of carriers have been successfully retrieved.", "carriers": [ { "scac": "string", "name": "string", "status": "PASSIVE" }, { "scac": "string", "name": "string", "status": "PASSIVE" } ], "meta": { "more": true, "total": 3005 } } ``` ``` -------------------------------- ### Get Shipments List Source: https://api.shipsgo.com/docs/v2/specs/openapi Retrieves a list of shipments based on specified filters. This endpoint is useful for obtaining an overview of shipments and their current status. ```APIDOC ## GET /websites/api_shipsgo_v2/ocean/shipments ### Description Retrieves a list of ocean shipments with various details. Supports filtering by reference, booking number, container number, and status. ### Method GET ### Endpoint `/websites/api_shipsgo_v2/ocean/shipments` ### Parameters #### Query Parameters - **reference** (string) - Optional - Your reference to remember or classify the shipment. - **booking_number** (string) - Optional - The booking number of the shipment. - **container_number** (string) - Optional - The container number of the shipment. - **status** (string) - Optional - The status to filter shipments. Allowed values: `NEW`, `INPROGRESS`, `BOOKED`, `LOADED`, `SAILING`, `ARRIVED`, `DISCHARGED`, `UNTRACKED`. ### Request Example ```http GET /websites/api_shipsgo_v2/ocean/shipments?status=SAILING&container_number=TEST1234567 ``` ### Response #### Success Response (200) - **id** (integer) - The unique identifier of the shipment. - **reference** (string) - Your reference to remember or classify the shipment. - **booking_number** (string) - The booking number of the shipment. - **container_number** (string) - The container number of the shipment. - **container_count** (integer) - The number of containers associated with the shipment. - **carrier** (object) - The carrier responsible for the shipment. - **scac** (string) - The Standard Carrier Alpha Code (SCAC) of the carrier. - **name** (string) - Name of the carrier. - **status** (string) - The current status of the shipment. - **route** (object) - Information about the shipment's route. - **port_of_loading** (object) - Details of the port of loading. - **location** (object) - Location details of the port. - **un_locode** (string) - UN/LOCODE of the port. - **name** (string) - Name of the port. - **country_code** (string) - ISO country code. - **name** (string) - Name of the port of loading. - **port_of_discharge** (object) - Details of the port of discharge. - **location** (object) - Location details of the port. - **un_locode** (string) - UN/LOCODE of the port. - **name** (string) - Name of the port. - **country_code** (string) - ISO country code. - **name** (string) - Name of the port of discharge. - **date_of_discharge** (string) - The date when the shipment is expected to be discharged. - **date_of_discharge_initial** (string) - The first declared discharge date provided by the carrier. - **transit_time** (integer) - The estimated transit time for the shipment in days. - **transit_percentage** (integer) - The percentage of the shipment's transit time that has been completed. - **co2_emission** (number) - Estimated total emissions values for the shipment (in tons). - **containers** (array) - Details of the containers associated with the shipment. - Each item is an object representing a container with its statuses, movement info, number, type, size, etc. - **tokens** (object) - Tokens for creating public links to shipment details. - **map** (string) - Token for the Shipsgo Map link. - **creator** (object) - Information about the shipment's creator. - **name** (string) - Full name of the creator. - **email** (string) - Email address of the creator. - **followers** (array) - Email addresses subscribed to receive notifications. - **tags** (array) - Labels or keywords associated with the shipment. - **created_at** (string) - Creation date of the shipment (UTC). - **updated_at** (string) - Date of the last update (UTC). - **checked_at** (string) - Date of the last time shipment was checked by Shipsgo (UTC). - **discarded_at** (string) - Timestamp (UTC) when the shipment was discarded. #### Response Example ```json { "data": [ { "id": 12345, "reference": "YOUR_REF_1", "booking_number": "BKNGXYZ", "container_number": "TEST1234567", "container_count": 1, "carrier": { "scac": "MSCU", "name": "Maersk Line" }, "status": "SAILING", "route": { "port_of_loading": { "location": { "un_locode": "CNSHA", "name": "Shanghai", "country_code": "CN" }, "name": "Port of Shanghai" }, "port_of_discharge": { "location": { "un_locode": "NLRTM", "name": "Rotterdam", "country_code": "NL" }, "name": "Port of Rotterdam" } }, "date_of_discharge": "2023-12-15", "date_of_discharge_initial": "2023-12-10", "transit_time": 30, "transit_percentage": 50, "co2_emission": 5.5, "containers": [ { "number": "TEST1234567", "type": "40GP", "status": "SAILING" } ], "tokens": { "map": "some-uuid-token" }, "creator": { "name": "John Doe", "email": "john.doe@example.com" }, "followers": ["john.doe@example.com"], "tags": [{"name": "urgent"}], "created_at": "2023-11-01T10:00:00Z", "updated_at": "2023-11-15T12:00:00Z", "checked_at": "2023-11-15T11:55:00Z", "discarded_at": null } ] } ``` ``` -------------------------------- ### List Endpoints - Filtering and Sorting Source: https://api.shipsgo.com/docs/v2/specs/postman-collection Describes the common structure for bulk fetches of API resources, including how to filter, sort, and paginate list endpoints. ```APIDOC ## List Endpoints - Filtering and Sorting ### Description Details how to perform bulk fetches on top-level API resources, including common structures for filtering, sorting, and pagination. ### Example Usage To list air shipments with upcoming arrivals in order: ```plain [GET] /air/shipments?filters[status]=eq:EN_ROUTE&order_by=date_of_rcf,asc ``` ### Filtering List endpoints support various filters that can be combined using the **AND** condition. The common structure is `filters[field]=operator:value(s)`. Refer to the specific endpoint documentation for available `field` and `operator` mappings. #### Supported Operators | Operator | Description | | -------------- | ------------------------------------------------------------------------- | | `eq` | Equal to a specific value. | | `not_eq` | Not equal to a specific value. | | `contains` | Checks if the field value contains a specific substring. | | `not_contains` | Checks if the field value does not contain a specific substring. | | `in` | Checks if the field value is within a list of values (`,` separated). | | `not_in` | Checks if the field value is not within a list of values (`,` separated). | | `with` | Checks if the field value is within a list of values (`,` separated). | | `without` | Checks if the field value is not within a list of values (`,` separated). | | `gt` | Greater than a specific value. | | `gte` | Greater than or equal to a specific value. | | `lt` | Less than a specific value. | | `lte` | Less than or equal to a specific value. | | `between` | Checks if the field value is between two values (`...` separated). | ### Sorting List endpoints can be sorted using the `order_by` parameter with the structure `order_by=field,direction`. `direction` can be `asc` (ascending) or `desc` (descending). If `direction` is omitted, it defaults to ascending. ``` -------------------------------- ### List Air Shipments by Tags and Creator (Plain Text) Source: https://api.shipsgo.com/docs/v2/specs/openapi Illustrates filtering air shipments based on associated tags and the creator's email address. ```plain /air/shipments ?filters[tags]=with:COMPANY_ABC &filters[creator]=eq:john-doe@example.com ``` -------------------------------- ### Get Air Shipment Details Source: https://api.shipsgo.com/docs/v2/specs/openapi Retrieves detailed information about a specific air shipment using its unique identifier. This endpoint is crucial for tracking and monitoring shipment progress. ```APIDOC ## GET /air/shipments/{shipment_id} ### Description This endpoint retrieves the details of an existing air shipment. It returns comprehensive information about the shipment. This allows users to track and monitor the shipment's progress and status in real-time. ### Method GET ### Endpoint /air/shipments/{shipment_id} ### Parameters #### Path Parameters - **shipment_id** (integer) - Required - The unique identifier of the shipment. ### Request Example ```json { "example": "No request body needed for GET request." } ``` ### Response #### Success Response (200) - **message** (string) - A message indicating the result (`SUCCESS`). - **shipment** (object) - Details of the shipment. - **id** (integer) - The unique identifier of the shipment. - **reference** (string) - Internal unique identifier for the shipment. - **awb_number** (string) - Air Waybill number. - **airline** (object) - Information about the airline. - **iata** (string) - IATA code of the airline. - **name** (string) - Name of the airline. - **cargo** (object) - Cargo details. - **pieces** (integer) - Number of pieces. - **weight** (number) - Weight of the cargo. - **volume** (number) - Volume of the cargo. - **status** (string) - Current status of the shipment (e.g., "INPROGRESS", "BOOKED"). - **status_split** (boolean) - Indicates if the status is split. - **status_extended** (object) - Extended status information. - **route** (object) - Shipment route details. - **origin** (object) - Origin details. - **location** (object) - Origin location details. - **iata** (string) - IATA code of the origin location. - **name** (string) - Name of the origin location. - **timezone** (string) - Timezone of the origin location. - **country** (object) - Country details. - **code** (string) - Country code. - **name** (string) - Country name. - **date_of_dep** (string) - Date of departure. - **date_of_dep_initial** (string) - Initial date of departure. - **ts_count** (integer) - Number of transit stops. - **destination** (object) - Destination details. - **location** (object) - Destination location details. - **iata** (string) - IATA code of the destination location. - **name** (string) - Name of the destination location. - **timezone** (string) - Timezone of the destination location. - **country** (object) - Country details. - **code** (string) - Country code. - **name** (string) - Country name. - **date_of_rcf** (string) - Date of arrival. - **date_of_rcf_initial** (string) - Initial date of arrival. - **transit_time** (integer) - Total transit time. - **transit_percentage** (integer) - Percentage of transit completed. - **movements** (array) - Array of shipment movement events. - **event** (string) - Type of event (e.g., "DEP", "ARR"). - **status** (string) - Status of the movement (e.g., "EST"). - **cargo** (object) - Cargo details for the movement. - **location** (object) - Location details for the movement. - **flight** (string) - Flight number. - **timestamp** (string) - Timestamp of the movement. - **tokens** (object) - Token information. - **followers** (array) - Array of follower objects. - **id** (integer) - Follower ID. - **email** (string) - Follower email. - **tags** (array) - Array of tag objects. - **id** (integer) - Tag ID. - **name** (string) - Tag name. - **creator** (object) - Creator information. - **name** (string) - Creator's name. - **email** (string) - Creator's email. - **created_at** (string) - Timestamp of creation. - **updated_at** (string) - Timestamp of last update. - **checked_at** (string) - Timestamp of last check. #### Response Example ```json { "message": "SUCCESS", "shipment": { "id": 123456, "reference": "INTERNAL_UNIQUE_IDENTIFIER", "awb_number": "176-88888888", "airline": { "iata": "EK", "name": "EMIRATES" }, "cargo": { "pieces": 28, "weight": 754.6, "volume": null }, "status": "BOOKED", "status_split": false, "status_extended": { "BOOKED": 28 }, "route": { "origin": { "location": { "iata": "ALC", "name": "Alicante–Elche Airport", "timezone": "Europe/Madrid", "country": { "code": "ES", "name": "Spain" } }, "date_of_dep": "2024-07-21T15:00:00+02:00", "date_of_dep_initial": "2024-07-20T15:00:00+02:00" }, "ts_count": 2, "destination": { "location": { "iata": "DXB", "name": "Dubai International Airport", "timezone": "Asia/Dubai", "country": { "code": "AE", "name": "United Arab Emirates" } }, "date_of_rcf": "2024-07-23T22:30:00+04:00", "date_of_rcf_initial": "2024-07-22T22:30:00+04:00" }, "transit_time": 53, "transit_percentage": 0 }, "movements": [ { "event": "DEP", "status": "EST", "cargo": { "pieces": 28, "weight": 754.6, "volume": null }, "location": { "iata": "ALC", "name": "Alicante–Elche Airport", "timezone": "Europe/Madrid", "country": { "code": "ES", "name": "Spain" } }, "flight": "EK4469T", "timestamp": "2024-07-21T15:00:00+02:00" } ], "tokens": { "map": "00000000-0000-0000-0000-000000000000" }, "followers": [ { "id": 1001, "email": "customer-1@example.com" }, { "id": 1002, "email": "customer-2@example.com" } ], "tags": [ { "id": 1001, "name": "IMPORT" }, { "id": 1002, "name": "CUSTOMER_A" } ], "creator": { "name": "John Doe", "email": "john-doe@example.com" }, "created_at": "2020-01-31 12:00:00", "updated_at": "2020-01-31 12:00:00", "checked_at": "2020-01-31 12:00:00" } } ``` ``` -------------------------------- ### Create Shipment API Request (POST /ocean/shipments) Source: https://api.shipsgo.com/docs/v2/specs/postman-collection This snippet demonstrates how to create a new shipment using the Shipsgo API. It requires authentication via an API key and accepts shipment details in JSON format. The API handles duplicate checks and concurrent request processing to prevent race conditions. ```json { "reference": "", "container_number": "", "booking_number": "", "carrier": "", "followers": [ "", "" ], "tags": [ "", "" ] } ```