### API Request Example for Getting Locations Source: https://docs.searates.com/reference/freight-index/manage-indices This example demonstrates how to make a GET request to the '/dictionary/locations' endpoint. It includes required query parameters for searching and specifying the location type, along with an example of an API key header. ```http GET /dictionary/locations?search=Hamburg&location_type=CITY HTTP/1.1 Host: api.searates.com X-API-KEY: YOUR_API_KEY Content-Type: application/json ``` -------------------------------- ### Get Routes Response Example Source: https://docs.searates.com/reference/route-planner/create-route Example JSON response when successfully retrieving a list of routes. Includes route numbers, creation, and update timestamps. ```json { "status_code": "OK", "data": [ { "number": "RP-JF87XKID", "created_at": "2024-12-23 09:53:28", "updated_at": "2024-12-23 09:54:42" }, { "number": "RP-7B8UZO0K", "created_at": "2024-12-23 10:57:33", "updated_at": "2024-12-23 10:57:33" } ] } ``` -------------------------------- ### Get Route Data API Request Example (URL) Source: https://docs.searates.com/reference/route-planner/create-route This example demonstrates how to construct a URL to retrieve data for a specific route using its route number. An API key must be included as a query parameter for authentication. ```bash GET /routes/{routeNumber}?api_key=123 ``` -------------------------------- ### API Request Example for Schedules by Port Source: https://docs.searates.com/reference/schedules/schedules-by-points This example demonstrates how to make a GET request to the 'get/schedules/by-port' endpoint. It includes the necessary API Key in the headers and specifies required query parameters like 'locode', 'from_date', and 'weeks', along with an optional 'carriers' filter. ```http GET /schedules/by-port?locode=USNYC&from_date=2024-04-02&weeks=3&carriers=MAEU,MSCU,COSU HTTP/1.1 Host: api.searates.com X-API-KEY: YOUR_API_KEY Content-Type: application/json ``` -------------------------------- ### API Request Example for Shipping Types Source: https://docs.searates.com/reference/freight-index/manage-indices This example shows a GET request to the '/dictionary/shipping-types' endpoint. It illustrates how to optionally include transport units and bulk sizes in the response by setting boolean query parameters. An API key is also required. ```http GET /dictionary/shipping-types?include_transport_units=true&include_bulk_sizes=true HTTP/1.1 Host: api.searates.com X-API-KEY: YOUR_API_KEY Content-Type: application/json ``` -------------------------------- ### Get Shipping Lines Info (JSON Response Example) Source: https://docs.searates.com/reference/tracking/historical-data This example demonstrates the JSON response structure when requesting information about supported shipping lines using the `get/info/sealines` endpoint. It includes details like the shipping line's name, active status, supported shipment types, and SCAC codes. ```json { "status": "success", "message": "OK", "data": [ { "name": "Mediterranean Shipping Company (MSC)", "active": true, "active_types": { "ct": true, "bl": true, "bk": true, "bl_ct": false, "bk_ct": false }, "maintenance": false, "scac_codes": [ "MSCU", "MEDU" ], "prefixes": [ "MSC", "MSD", "MSM", "MSB", "MSG", "MAD", "MSP", "MSZ", "GTI", "MED", "MSY", "MST", "MSN", "MSV" ] }, { "name": "ZIM", "active": true, "active_types": { "ct": true, "bl": true, "bk": true, "bl_ct": false, "bk_ct": false }, "maintenance": false, "scac_codes": [ "ZIMU" ], "prefixes": [ "ZCL", "ZCS", "ZIM", "ZMO", "ZWF" ] } ] } ``` -------------------------------- ### Get Terminal Data Example (JSON) Source: https://docs.searates.com/reference/terminal-tracking/get-list-of-supported-terminals This example demonstrates a successful response when retrieving terminal tracking data for a specific container. It includes details about the terminal, container status, and a history of tracking events. ```json { "status_code": "OK", "metadata": { "request_parameters": { "terminal_code": "AEKHLADT", "container_number": "SEKU5738515" } }, "data": { "terminal": { "name": "KHALIFA PORT CONTAINER TERMINAL", "operator": "ABU DHABI TERMINALS", "address": "Khalifa Port Container Terminal Building 70 Taweelah, Abu Dhabi, U.A.E.", "website": "https://www.adterminals.ae", "country_code": "AE", "locode": "AEKHL", "bic_code": null, "smdg_code": "AEKHLADT", "lat": 24.8075, "lng": 54.649444 }, "container": { "number": "SEKU5738515", "iso_code": "45G1", "size_type": "40' High Cube Dry", "status": "NOT_ON_TERMINAL", "updated_at": "2025-05-16 08:29:52", "events": [ { "description": "GATE_IN", "event_code": "GTIN", "datetime": "2024-09-15 17:18:00", "is_actual": true, "is_empty": true, "transport_type": null, "vessel_name": null, "voyage": null }, { "description": "GATE_OUT", "event_code": "GTOT", "datetime": "2024-12-12 03:28:00", "is_actual": true, "is_empty": true, "transport_type": "TRUCK", "vessel_name": null, "voyage": null }, { "description": "GATE_IN", "event_code": "GTIN", "datetime": "2024-12-13 03:58:00", "is_actual": true, "is_empty": false, "transport_type": null, "vessel_name": null, "voyage": null }, { "description": "LOAD", "event_code": "LOAD", "datetime": "2024-12-17 17:53:00", "is_actual": true, "is_empty": false, "transport_type": "VESSEL", "vessel_name": null, "voyage": null } ] } } } ``` -------------------------------- ### Get Route Data API Request Example (cURL) Source: https://docs.searates.com/reference/route-planner/delete-route This example demonstrates how to retrieve route data using the API. It requires an API key and the route number as path parameters. The response includes detailed information about the specified route. ```bash curl -X GET \ 'https://api.searates.com/v1/routes/RP-F2RQ19IK?api_key=YOUR_API_KEY' \ -H 'Content-Type: application/json' ``` -------------------------------- ### Get Route Data Request Example (HTTP) Source: https://docs.searates.com/reference/route-planner/general-information This example demonstrates how to request route data using the Searates API. It requires the route number as a path parameter and an API key as a query parameter for authentication. The response will contain detailed information about the specified route. ```http GET /routes/RP-F2RQ19IK?api_key=123 HTTP/1.1 Host: api.searates.com Content-Type: application/json ``` -------------------------------- ### Get Port Entry Response Example Source: https://docs.searates.com/reference/schedules/get-vessel-entry This JSON object provides detailed information about a specific port, identified by its UN/LOCODE. It includes the port's name, state, country, coordinates, and timezone. ```json { "success": true, "status_code": "OK", "data": { "port": { "name": "New York", "state": "New York", "country": "United States", "country_code": "US", "locode": "USNYC", "lat": 40.6759, "lng": -74.0829, "timezone": "America/New_York" } } } ``` -------------------------------- ### Get Historical Shipping Data (JSON Response Example) Source: https://docs.searates.com/reference/tracking/historical-data This example shows the JSON response for the `get/history` endpoint, which retrieves historical shipping data. It includes metadata about the request, such as the shipment type, number, and API call usage, along with a list of past requests. ```json { "status": "success", "message": "OK", "data": { "metadata": { "type": "CT", "number": "MSKU7117653", "sealine": "", "sealine_name": null, "status": "UNKNOWN", "updated_at": "2023-06-15 12:00:23", "api_calls": { "total": 100, "used": 1, "remaining": 99 }, "unique_shipments": { "total": 0, "used": 0, "remaining": 0 } }, "requests": [ { "date": "2021-07-25 10:58:04", "sealine": "maeu", "id": 61118083 }, { "date": "2021-08-15 19:15:59", "sealine": "maeu", "id": 67771922 }, { "date": "2022-02-03 06:23:53", "sealine": "maeu", "id": 134036490 }, { "date": "2022-05-24 12:34:54", "sealine": "maeu", "id": 182782146 }, { "date": "2022-06-22 09:08:02", "sealine": "maeu", "id": 196885782 }, { "date": "2022-10-12 07:31:10", "sealine": "maeu", "id": 260377336 }, { "date": "2023-02-03 05:28:37", "sealine": "maeu", "id": 306555693 }, { "date": "2023-02-07 09:54:26", "sealine": "maeu", "id": 308285366 }, { "date": "2023-05-22 07:25:51", "sealine": "maeu", "id": 356065796 }, { "date": "2023-06-15 10:30:06", "sealine": "maeu", "id": 366830221 } ] } } ``` -------------------------------- ### User Info API Request Example Source: https://docs.searates.com/reference/freight-index/manage-indices This example demonstrates how to request user information and API statistics using the `post/user` endpoint. It requires an API key in the headers. ```json { "profile_id": "12345" } ``` -------------------------------- ### Get Carriers List - Response Example Source: https://docs.searates.com/reference/freight-index/carriers-list An example JSON response for the 'Get Carriers List' endpoint, showing a list of shipping carriers with their IDs, names, short names, and types. ```json { "data": [ { "id": 10, "name": "Maersk", "short_name": "MAEU", "type": "SEALINE" }, { "id": 137, "name": "Maersk Spot", "short_name": "MAEU", "type": "SEALINE" } ] } ``` -------------------------------- ### Get Carriers List - Example Request Headers Source: https://docs.searates.com/reference/freight-index/get-user-info Example of headers required for the 'get/dictionary/carriers' endpoint. An API key is mandatory for authentication. ```HTTP Content-Type: application/json X-API-KEY: YOUR_API_KEY ``` -------------------------------- ### Get Shipping Schedules Source: https://docs.searates.com/spec/schedules-v2-openapi Retrieves shipping schedules based on carrier, location code, start date, and number of weeks. ```APIDOC ## GET /websites/searates ### Description Retrieves shipping schedules for a specified carrier, port, and date range. ### Method GET ### Endpoint /websites/searates ### Parameters #### Query Parameters - **carriers** (string) - Required - The SCAC code of the carrier (e.g., MSCU). - **locode** (string) - Required - The UN/LOCODE of the port (e.g., USNYC). - **from_date** (string) - Required - The start date for the schedule search in YYYY-MM-DD format. - **weeks** (integer) - Required - The number of weeks to look ahead for schedules. ### Request Example (No request body for GET requests) ### Response #### Success Response (200) - **success** (boolean) - Indicates if the request was successful. - **status_code** (string) - The status code of the response (e.g., OK, SCHEDULES_FOUND). - **metadata** (object) - Contains request parameters and response statistics. - **request_parameters** (object) - The parameters used in the request. - **response_stats** (array) - Statistics about the found schedules. - **data** (object) - Contains the schedule information. - **schedules** (array) - An array of schedule objects. - **schedule_id** (string) - Unique identifier for the schedule. - **carrier_name** (string) - The name of the carrier. - **carrier_scac** (string) - The SCAC code of the carrier. - **port_name** (string) - The name of the port. - **port_locode** (string) - The UN/LOCODE of the port. - **all_voyages** (array) - A list of all voyage codes associated with the schedule. - **calling_vessels** (array) - Details about vessels calling at the port. - **order_id** (integer) - The order of the vessel in the schedule. - **voyages** (array) - List of voyages for this vessel. - **skip** (boolean) - Indicates if the vessel skips this port. - **estimated_dates** (object) - Estimated arrival and departure dates. - **actual_dates** (object) - Actual arrival and departure dates. - **vessel_name** (string) - The name of the vessel. - **vessel_imo** (integer) - The IMO number of the vessel. - **terminal_name** (string) - The name of the terminal. - **terminal_code** (string) - The code of the terminal. - **service_name** (string) - The name of the shipping service. - **service_code** (string) - The code of the shipping service. - **cut_off_dates** (array) - Cut-off dates for cargo. #### Response Example ```json { "success": true, "status_code": "OK", "metadata": { "request_parameters": { "carriers": "MSCU", "locode": "USNYC", "from_date": "2024-08-15", "weeks": 1 }, "response_stats": [ { "status_code": "SCHEDULES_FOUND", "carrier_name": "MSC", "found_schedules": 1 } ] }, "data": { "schedules": [ { "schedule_id": "07bf0d4adb8c242aad4582ca9a62d7d4bc1a8a4e", "carrier_name": "MSC", "carrier_scac": "MSCU", "port_name": "NEW YORK", "port_locode": "USNYC", "all_voyages": [ "CG429R", "PH432R", "IU432R", "432W", "MZ432R", "UL430W", "XA425A", "XA431R", "NG430W", "ME429W", "ME433E", "427W", "433E", "431E", "IU426A", "IU433R", "NN429A", "428E", "433W", "431W", "PD432A", "432E", "CG430R", "UZ432S", "ME430W", "ME434E", "MZ433R", "IU427A" ], "calling_vessels": [ { "order_id": 1, "voyages": [ { "name": "Departure Voyage", "voyage": "CG429R" } ], "skip": false, "estimated_dates": { "arrival_date": null, "berth_date": null, "departure_date": "2024-08-13 03:36:00" }, "actual_dates": { "arrival_date": null, "berth_date": null, "departure_date": null }, "vessel_name": "MSC BALTIC III", "vessel_imo": 9241475, "terminal_name": null, "terminal_code": null, "service_name": "CANADA GULF BRIDGE", "service_code": null, "cut_off_dates": [] }, { "order_id": 2, "voyages": [ { "name": "Departure Voyage", "voyage": "PH432R" } ], "skip": false, "estimated_dates": { "arrival_date": null, "berth_date": null, "departure_date": "2024-08-13 06:00:00" }, "actual_dates": { "arrival_date": null, "berth_date": null, "departure_date": null }, "vessel_name": "MSC BALTIC III", "vessel_imo": 9241475, "terminal_name": null, "terminal_code": null, "service_name": "CANADA GULF BRIDGE", "service_code": null, "cut_off_dates": [] } ] } ] } } ``` ``` -------------------------------- ### Create Route Request Body Example Source: https://docs.searates.com/reference/route-planner/create-route Example JSON body for creating a new route. Specifies waypoints with optional details like type, name, coordinates, and events. ```json { "waypoints": [ { "type": "SEA", "name": "Izmir", "country_code": "TR", "locode": "TRIZM", "lat": 38.41273, "lng": 27.13838, "events": [ { "description": "Vessel departure", "datetime": "2024-11-23 13:37:00", "vessel": "MAERSK VALPARAISO", "voyage": "447S" } ], "transport_mode_to_next": "SEA" } ] } ``` -------------------------------- ### GET /schedules/by-port Source: https://docs.searates.com/reference/schedules/get-carrier-entry Fetches voyage schedules for a specified port, with optional filtering by carriers, start date, and number of weeks. ```APIDOC ## GET /schedules/by-port ### Description Retrieves shipping schedules for a particular port using its UN/LOCODE, and optionally filters by SCACs for carriers. Requires an API Key for authentication. ### Method GET ### Endpoint /schedules/by-port ### Parameters #### Path Parameters None #### Query Parameters - **carriers** (string) - Optional - SCAC codes list. Example: `MAEU,MSCU,COSU,ONEY,HDMU,OOLU,YMLU,EGLV,CMDU`. Match pattern: `^([A-Z0-9]{4}(?:(,[A-Z0-9]{4})){0,})$` - **locode** (string) - Required - Port UN/LOCODE. Example: `USNYC`. Match pattern: `^[A-Z0-9]{5}$` - **from_date** (string) - Required - Start from date in `yyyy-mm-dd` format. Must be the current date or a future date. Example: `2024-04-02`. Match pattern: `^(\d{4}-\d{2}-\d{2})$` - **weeks** (integer) - Required - Number of weeks ahead to display. Must be between 1 and 6 (inclusive). Example: `3` #### Request Body None ### Request Example None ### Response #### Success Response (200) - **order_id** (integer) - The unique identifier for the order. - **voyages** (array) - A list of voyages associated with the order. - **name** (string) - The name of the voyage stage (e.g., 'arrival', 'departure'). - **voyage** (string) - The voyage identifier. - **skip** (boolean) - Indicates if the schedule is skipped. - **estimated_dates** (object) - Estimated dates for the voyage stages. - **arrival_date** (string) - Estimated arrival date and time. - **berth_date** (string | null) - Estimated berth date and time. - **departure_date** (string) - Estimated departure date and time. - **actual_dates** (object) - Actual dates for the voyage stages. - **arrival_date** (string | null) - Actual arrival date and time. - **berth_date** (string | null) - Actual berth date and time. - **departure_date** (string | null) - Actual departure date and time. - **port_name** (string) - The name of the port. - **port_locode** (string) - The UN/LOCODE of the port. - **terminal_name** (string | null) - The name of the terminal. - **terminal_code** (string | null) - The code of the terminal. - **cut_off_dates** (array) - A list of cut-off dates. - **updated_at** (string) - The timestamp when the record was last updated. #### Response Example ```json { "order_id": 13, "voyages": [ { "name": "arrival", "voyage": "059W" }, { "name": "departure", "voyage": "059W" } ], "skip": false, "estimated_dates": { "arrival_date": "2024-06-19 18:00:00", "berth_date": null, "departure_date": "2024-06-24 03:00:00" }, "actual_dates": { "arrival_date": null, "berth_date": null, "departure_date": null }, "port_name": "Los Angeles, California", "port_locode": "USLAX", "terminal_name": null, "terminal_code": null, "cut_off_dates": [] } ``` ### Security API Key: `X-API-KEY` header ``` -------------------------------- ### Untitled Source: https://docs.searates.com/reference/carbon-emissions/historical-data No description -------------------------------- ### Update Route API Request Example (URL) Source: https://docs.searates.com/reference/route-planner/create-route This example shows how to format a URL for updating an existing route. The route number is specified in the path, and an API key is required in the query parameters for authentication. ```bash PUT /routes/{routeNumber}?api_key=123 ``` -------------------------------- ### Create Route Response Example (JSON) Source: https://docs.searates.com/reference/route-planner/general-information This is an example of a successful response when creating a new route. It includes a status code and detailed data about the created route, such as its number, creation timestamps, and a list of waypoints with associated events. ```json { "status_code": "OK", "data": { "number": "RP-F2RQ19IK", "created_at": "2024-12-26 09:55:00", "updated_at": "2024-12-26 09:55:00", "waypoints": [ { "type": "SEA", "description": null, "name": "Izmir", "state": null, "country": null, "country_code": "TR", "locode": "TRIZM", "lat": 38.41273, "lng": 27.13838, "events": [ { "description": "Load", "datetime": "2024-11-23 13:37:00", "vessel": "MAERSK VALPARAISO", "voyage": "447S" }, { "description": "Vessel departure", "datetime": "2024-11-23 19:21:00", "vessel": "MAERSK VALPARAISO", "voyage": "447S" } ], "transport_mode_to_next": "SEA", "path_to_next": [] }, { "type": "SEA", "description": null, "name": "Port Said East", "state": null, "country": null, "country_code": "EG", "locode": "EGPSE", "lat": 31.216666666667, "lng": 32.35, "events": [ { "description": "Vessel arrival", "datetime": "2024-11-27 14:33:00", "vessel": "MAERSK VALPARAISO", "voyage": "447S" } ], "transport_mode_to_next": null, "path_to_next": [] } ] } } ``` -------------------------------- ### Request Sample for Container Loading Optimization Source: https://docs.searates.com/reference/load-calculator/introduction An example JSON request body demonstrating how to specify options, groups, items, and auto-container preferences for the Searates API. It includes detailed pallet and item configurations. ```json { "options": { "lengthUnits": "mm", "weightUnits": "kg", "lengthAccuracy": 5, "remainsNear": true }, "groups": [ { "name": "Group #1", "uid": 111, "color": "#000", "pallets": { "uid": "1dca98", "color": "#000", "size": { "length": 1200, "width": 800, "height": 2000 }, "stacking": { "maxHeight": null, "layers": 3, "fill": 0.85 }, "weight": 10, "maxWeight": 1500, "depth": 100, "name": "euro", "type": "euro" }, "items": [ { "color": "#23b753", "index": 1, "name": "Boxes 1", "qty": "400", "type": "box", "uid": "2222", "weight": 10, "size": { "length": 500, "width": 400, "height": 300, "radius": null }, "stacking": { "tiltX": true, "tiltY": false, "layers": null, "topWeight": null, "height": null, "fill": null, "rollPlacement": null } } ] } ], "containers": [], "autoContainers": [ { "attr": { "type": "20st" }, "spaces": [ { "length": 5890, "width": 2350, "height": 2390, "maxWeight": 28230 } ] }, { "attr": { "type": "40st" }, "spaces": [ { "length": 12020, "width": 2350, "height": 2390, "maxWeight": 26700 } ] }, { "attr": { "type": "40hq" }, "spaces": [ { "length": 12020, "width": 2350, "height": 2690, "maxWeight": 26460 } ] } ], "auth": { "demo": false, "user": false }, "errorProducts": [], "palletCheckLoader": false } ``` -------------------------------- ### GraphQL API Endpoint and Authentication Example Source: https://docs.searates.com/reference/carbon-emissions/by-coordinates Demonstrates the GraphQL API endpoint for SeaRates and provides an example of how to include an authorization token in the request headers. This is crucial for authenticating API requests. ```http POST https://www.searates.com/graphql_co2 Headers: {"Authorization": "Bearer {token}"} Body: { "query": "{ co2ByCoordinates( latFrom: 19.0759837 lngFrom: 72.8776559 latTo: 49.2827291 lngTo: -123.1207375 shippingType: \"air\" transportType: \"default\" isRef: false containerType: \"ot20\" weight: 15 ) { amount price } }" } ``` -------------------------------- ### Track Shipment by Bill of Lading (BL) - API Request Example Source: https://docs.searates.com/spec/postman/tracking-v3.postman_collection This example shows how to make a GET request to the Searates API to track a shipment using a Bill of Lading (BL) number. It includes query parameters for API key, shipment number, type, sealine, and update options. ```http GET {{baseUrl}}/reference?api_key=string&number=HLCUXM1230445340&type=BL&sealine=maeu&force_update=false&route=false&ais=false HTTP/1.1 Host: {{baseUrl}} Accept: application/json Authorization: ApiKey {{apiKey}} ``` -------------------------------- ### Request Header for API Key Authentication Source: https://docs.searates.com/reference/freight-index/introduction This example demonstrates how to include an API key in the request header for authentication. The API key should be passed as 'X-API-KEY'. ```http X-API-KEY: 123 ``` -------------------------------- ### API Request Example (get/air/history) Source: https://docs.searates.com/reference/air-tracking/general-information Example of how to call the 'get/air/history' endpoint to retrieve historical air cargo data. This request requires an API key for authentication and an air waybill number to specify the cargo. The Content-Type header should be set to application/json. ```http GET /air/history?api_key=YOUR_API_KEY&number=020-17363006 HTTP/1.1 Host: api.searates.com Content-Type: application/json ``` -------------------------------- ### Get Carriers List - Example Request Source: https://docs.searates.com/reference/freight-index/get-locations This endpoint retrieves a list of carriers, optionally filtered by name. It requires an API Key for authentication. ```HTTP GET /dictionary/carriers Headers: X-API-KEY: YOUR_API_KEY Content-Type: application/json Query Parameters: search: Optional string for searching carrier names carrier_type: Optional string for filtering by carrier type ``` -------------------------------- ### API Endpoint: Get Tariffs Response Example Source: https://docs.searates.com/reference/demurrage-and-storage/calculate This JSON object shows a successful response for the 'Get Tariffs' endpoint. It contains `storage` information (currently null) and two arrays: `demurrage` and `detention`. Each item in these arrays specifies a day range (`sinceDay`, `untilDay`), the `rate`, and the `currency`. ```json { "code": 200, "data": { "storage": null, "demurrage": [ { "sinceDay": 1, "untilDay": 10, "rate": 0, "currency": "EUR" }, { "sinceDay": 11, "untilDay": 17, "rate": 20, "currency": "EUR" }, { "sinceDay": 18, "untilDay": 99, "rate": 40, "currency": "EUR" } ], "detention": [ { "sinceDay": 1, "untilDay": 10, "rate": 0, "currency": "EUR" }, { "sinceDay": 11, "untilDay": 17, "rate": 20, "currency": "EUR" }, { "sinceDay": 18, "untilDay": 99, "rate": 40, "currency": "EUR" } ] } } ``` -------------------------------- ### Authorization Header Example Source: https://docs.searates.com/reference/booking-system/create-new-booking Example of how to include the obtained bearer token in the Authorization header for API requests. ```http Authorization: Bearer 123 ```