> ## Documentation Index > Fetch the complete documentation index at: https://docs.datadocked.com/llms.txt > Use this file to discover all available pages before exploring further. # Vessels by Type & Country > Search vessels by specific type, flag country, or both — paginated, 100 per page Returns a paginated list of vessels filtered by their specific type, by their flag country, or by both at once. Reads the local database directly — no external providers involved, so latency is fast and consistent. **Credits:** 10 credits per request, charged only when at least one vessel is returned. Empty results, validation errors, and auth failures cost nothing. | | | | ---------- | --------------------------------- | | Method | `GET` | | Endpoint | `/vessels-by-types-and-countries` | | Rate limit | 50 requests / minute per API key | | Page size | 100 records, fixed | ## Request Parameters | Parameter | Type | Required | Description | | --------------- | ------- | ------------------------------------- | ---------------------------------------------------------------------- | | `type_specific` | string | At least one of these two is required | Vessel specific type. Must be one of the accepted values listed below. | | `country` | string | At least one of these two is required | Vessel flag country. Must be one of the accepted values listed below. | | `page` | integer | No (default: `1`) | Page number, starting at 1. | ### Validation Rules 1. **At least one filter is required.** `type_specific` alone, `country` alone, or both together. Sending neither returns 422. 2. **Values must come from the accepted lists below.** This is not a free-text search — use dropdowns or autocomplete, not text inputs. 3. **Matching is case-insensitive** and ignores leading/trailing spaces. `bulk carrier`, `Bulk Carrier`, and `BULK CARRIER` are all accepted. 4. **`page` must be ≥ 1.** `page=0` or negative values return 422. ### Example Requests ``` GET /api/vessels_operations/vessels-by-types-and-countries?type_specific=Bulk%20Carrier&country=Panama GET /api/vessels_operations/vessels-by-types-and-countries?country=Panama&page=3 GET /api/vessels_operations/vessels-by-types-and-countries?type_specific=Crude%20Oil%20Tanker ``` ## Response — 200 ```json theme={null} { "total": 2417, "items": [ { "name": "EVER_GALLANT", "mmsi": "373843000", "imo": "9624328", "callsign": "3EUN3", "country": "Panama", "countryIso": "PA", "shipType": "Cargo vessels", "typeSpecific": "Bulk Carrier" } ], "limit": 100, "page": 1 } ``` | Field | Type | Notes | | ------- | ------- | ---------------------------------------------------------------------------------------- | | `total` | integer | Total matches across all pages. Use this for pagination — it is not the size of `items`. | | `items` | array | Up to 100 vessels for the requested page. | | `limit` | integer | Always `100`. | | `page` | integer | Echo of the requested page number. | ### Item Fields Every field inside an item is nullable. Identifiers are normally present. | Field | Type | Notes | | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------- | | `name` | string \| null | Vessel name. Often stored with underscores instead of spaces (e.g. `EVER_GALLANT`). | | `mmsi` | string \| null | 9-digit MMSI, returned as a string. | | `imo` | string \| null | 7-digit IMO, returned as a string. **`"0"` means the vessel has no IMO** — do not render it as an identifier. | | `callsign` | string \| null | Radio call sign. | | `country` | string \| null | Flag country. | | `countryIso` | string \| null | 2-letter ISO country code, useful for flag icons. | | `shipType` | string \| null | Broad category, e.g. `Cargo vessels`. | | `typeSpecific` | string \| null | Specific vessel type — same vocabulary as the `type_specific` filter. | ### Empty Results An empty result set is a normal 200, not an error: ```json theme={null} { "total": 0, "items": [], "limit": 100, "page": 12 } ``` This is returned for a valid filter combination with no matching vessels, or for a page past the end of the result set. No credit is charged. **Casing quirk:** The database stores some values in inconsistent casing — there are rows with `Albania` and rows with `ALBANIA`, rows with `Fishing vessel` and rows with `Fishing Vessel`. Filtering is case-insensitive so a single query returns all of them, but `country` and `typeSpecific` in the response carry the raw stored value. **A single page of results can legitimately contain both spellings of the same country or type.** If you group, sort, or deduplicate on those fields client-side, compare them case-insensitively. ## Errors ### 422 — No filter provided ```json theme={null} { "detail": [ { "field": "type_specific, country", "value": null, "message": "At least one of 'type_specific' or 'country' must be provided." } ] } ``` ### 422 — Value not in the accepted list `detail` is an array with one entry per rejected field, so a request with two invalid values returns two entries. A filter that was not sent is never reported. ```json theme={null} { "detail": [ { "field": "type_specific", "value": "Frigate", "message": "Invalid value for 'type_specific'. Acceptable values are listed in 'allowed_values'.", "allowed_values": ["Bulk Carrier", "Crude Oil Tanker", "..."] } ] } ``` `allowed_values` always contains the complete list for that field. You can populate dropdowns at runtime instead of hardcoding: send one deliberately invalid request (e.g. `type_specific=__list__`) and read the lists from the 422 response. Validation happens before billing — neither request costs a credit. The standard FastAPI 422 (missing header, `page` not a number) has a different `detail` shape. Check for `detail[i].field` before relying on the custom structure above. ### Other Status Codes | Code | Meaning | Recommended handling | | ---- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | 400 | Insufficient credits, or endpoint blocked for this key. Body: `{"detail": "Not enough credits or endpoint in black list."}` | Show the message; offer to top up credits. | | 401 | Invalid API key. | Re-authenticate. | | 429 | More than 50 requests/minute. Body: `{"detail": "Too Many Requests"}` | Back off; debounce filter inputs so each keystroke does not fire a request. | | 503 | Database temporarily unavailable. | Retry after a short delay. | *** ## Accepted Values for `type_specific` 361 accepted values. Matching is case-insensitive. ```json theme={null} [ "Accommodation Jack Up", "Accommodation Platform", "Accommodation Ship", "Aggregates Carrier", "Air Cushion Ro-Ro/Passenger Ship", "Air Cushion Vehicle (Hovercraft)", "Anchor Handling Vessel", "Anchor Hoy", "Anti-Pollution", "Anti-polution", "Articulated Pusher Tug", "Asphalt/Bitumen Tanker", "Barge Carrier", "Beacon, Cardinal E", "Beacon, Cardinal N", "Beacon, Cardinal S", "Beacon, Cardinal W", "Beacon, Isolated danger", "Beacon, Port Hand", "Beacon, Preferred Channel Port hand", "Beacon, Preferred Channel Starboard hand", "Beacon, Safe Water", "Beacon, Special Mark", "Beacon, Starboard Hand", "Bitumen Tanker", "Bucket Ladder Dredger", "Bulk Carrier", "Bulk/Oil Carrier", "Bunkering Tanker", "Buoy-Laying Vessel", "Buoy/Lighthouse Vessel", "Cable Layer", "Caprolactam Tanker", "Cardinal Mark E", "Cardinal Mark N", "Cardinal Mark S", "Cardinal Mark W", "Cargo", "Cargo - Hazard A (Major)", "Cargo - Hazard B", "Cargo - Hazard C (Minor)", "Cargo - Hazard D (Recognizable)", "Cargo ship", "Cargo ship (HAZ-A)", "Cargo ship (HAZ-B)", "Cargo ship (HAZ-C)", "Cargo ship (HAZ-D)", "Cement Carrier", "Chemical Tanker", "Chemical/Oil Products Tanker", "CO2 Tanker", "Coal/Oil Mixture Tanker", "Combat Vessel", "Container Ship", "Crane Barge", "Crane Jack Up", "Crane Ship", "Crew Boat", "Crude Oil Tanker", "Cutter Suction Dredger", "Deck Cargo Pontoon", "Deck Cargo Ship", "Dive Vessel", "Diving ops", "Diving Support Vessel", "Dredger", "Dredging or UW ops", "Dredging Pontoon", "Drill Barge", "Drill Ship", "Drilling Jack Up", "Drilling Ship", "Dry Storage", "Edible Oil Tanker", "Exhibition Ship", "Factory Trawler", "Fire Fighting Vessel", "Fish Carrier", "Fish Factory", "Fish Factory Ship", "Fishery Patrol Vessel", "Fishery Research Vessel", "Fishing", "Fishing Support Vessel", "Fishing Vessel", "Floating Crane", "Floating Hotel/Restaurant", "Floating Linkspan", "Floating Sheerleg", "Floating Storage/Production", "FPSO", "Fruit Juice Tanker", "FSO", "General Cargo", "General Cargo Ship", "Grab Dredger", "Heavy Lift Vessel", "Heavy Load Carrier", "High Speed Craft", "Hopper Barge", "Hopper Dredger", "Hospital Ship", "Hospital Vessel", "Hovercraft", "HSC", "HSC (HAZ-A)", "HSC (HAZ-B)", "HSC (HAZ-C)", "HSC (HAZ-D)", "Hydrofoil", "Icebreaker", "Inland Cargo", "Inland Dredger", "Inland Passenger", "Inland Passenger Ship", "Inland Ro-Ro Cargo Ship", "Inland Supply Vessel", "Inland Tanker", "Inland Tug", "Inland, Bulk Carrier maritime", "Inland, Bunkership", "Inland, Catamaran Fast", "Inland, Container Vessel", "Inland, Cruise Ship", "Inland, Fast Ship", "Inland, Ferry", "Inland, Fishing Boat", "Inland, Freightbarge", "Inland, Freightbarge with Containers", "Inland, Gas Tanker", "Inland, General Cargo maritime", "Inland, Maintainance Craft, Cableship, Dredger", "Inland, Motor Freighter", "Inland, Motor Freighter Pushing Freighter(s)", "Inland, Motor Freighter pushing Tank-ship(s)", "Inland, Motor Freighter with Ships Alongside", "Inland, Motor Freighter with Tanker", "Inland, Motor Freighter, Tug", "Inland, Motor Tanker", "Inland, Motor Tanker, dry cargo as if liquid", "Inland, Motor Tanker, liquid cargo, type C", "Inland, Motor Tanker, liquid cargo, type N", "Inland, Motor Tanker, Tug", "Inland, Object, not otherwise specified", "Inland, Object, Towed, not otherwise specified", "Inland, Passenger Ship without Accommodation", "Inland, Passenger Ship, Ferry, Cruise ship", "Inland, Pleasure Craft, >20 metres", "Inland, Pushboat, Single", "Inland, Pushtow, eigth cargo barges", "Inland, Pushtow, five cargo barges", "Inland, Pushtow, four barges at least one tanker", "Inland, Pushtow, four cargo barges", "Inland, Pushtow, one cargo barge", "Inland, Pushtow, one tank/gas barge", "Inland, Pushtow, seven barges at least one tanker", "Inland, Pushtow, six cargo barges", "Inland, Pushtow, three cargo barges", "Inland, Pushtow, two cargo barges", "Inland, Red Cross Ship", "Inland, Service Vessel, Police Patrol", "Inland, Tankbarge", "Inland, Tankbarge, Gas", "Inland, Tankbarge, liquid cargo, type C", "Inland, Tankbarge, liquid cargo, type N", "Inland, Tanker", "Inland, Tug Freighter, coupled", "Inland, Tug, assisting a vessel or combination", "Inland, Tug, Freighter", "Inland, Tug, one or more tows", "Inland, Tug, single", "Inland, Tug, Tanker", "Inland, Unit Carrier maritime", "Inland, Unknown", "Isolated Danger", "Kelp Dredger", "Landing Craft", "Law Enforce", "Law enforcment", "Leading Light Front", "Leading Light Rear", "Leisure Vessels", "Light Vessel - LANBY - Rig", "Light, with Sectors", "Light, without Sectors", "Limestone Carrier", "Liquefied Gas", "Livestock Carrier", "LNG Tanker", "Local type", "Local Vessel", "Logistics Naval Vessel", "LPG Tanker", "LPG/Chemical Tanker", "Maintenance Platform", "Manned VTS", "Medical", "Medical Trans", "Military Ops", "Minesweeper", "Mining Vessel", "Mission Ship", "Molasses Tanker", "Mooring Vessel", "Motor Hopper", "Multi Purpose Offshore Vessel", "Museum Ship", "Naval Auxiliary Vessel", "Naval Craft", "Naval Research Vessel", "Naval Salvage Vessel", "Naval/Naval Auxiliary", "Navigation Aid", "Non Propelled Barge", "Nuclear Fuel Carrier", "Obo Carrier", "Offshore Construction Jack Up", "OffShore Structure", "Offshore Supply Ship", "Offshore Support Vessel", "Offshore Tug/Supply Ship", "Oil Products Tanker", "Oil/Chemical Tanker", "Ore Carrier", "Ore/Oil Carrier", "Other", "Other Non Merchant Ships", "Other type", "Other type (HAZ-A)", "Other type (HAZ-B)", "Other type (HAZ-C)", "Other type (HAZ-D)", "Pallet Carrier", "Palletised Cargo Ship", "Passenger", "Passenger (Cruise) Ship", "Passenger Ship", "Passenger ship (HAZ-A)", "Passenger ship (HAZ-B)", "Passenger ship (HAZ-C)", "Passenger ship (HAZ-D)", "Passenger/Cargo Ship", "Passenger/Container Ship", "Passenger/General Cargo Ship", "Passenger/Landing Craft", "Passenger/Ro-Ro Cargo", "Passenger/Ro-Ro Cargo Ship", "Patrol Vessel", "Pile Driving Vessel", "Pilot", "Pilot Ship", "Pilot Vessel", "Pipe Burying Vessel", "Pipe Layer", "Pipelay Crane Vessel", "Platform", "Pleasure Craft", "Pollution Control Vessel", "Pontoon", "Port Hand Mark", "Port Tender", "Powder Carrier", "Power Station Pontoon", "Power Station Vessel", "Preferred Channel Port Hand", "Preferred Channel Starboard Hand", "Production Testing Vessel", "Pusher Tug", "RACON", "Rail/Vehicles Carrier", "Reefer", "Reference Point", "Refrigerated Cargo Ship", "Replenishment Vessel", "Research Vessel", "Research/Survey Vessel", "Reserved", "Resolution 18 ship", "Ro-Ro Cargo", "Ro-Ro Cargo Ship", "Ro-Ro/Container Carrier", "Ro-Ro/Passenger Ship", "Rocket Launch Support Ship", "Safe Water", "Sail Training Ship", "Sailing Vessel", "Salvage Ship", "Salvage/Rescue Vessel", "SAR", "SAR Aircraft", "Seal Catcher", "Search & Rescue Vessel", "Self Discharging Bulk Carrier", "Sludge Carrier", "Spare", "Special Craft", "Special Mark - Sea Farm", "Special Vessel", "Standby Safety Vessel", "Starboard Hand Mark", "Suction Dredger", "Supply Tender", "Supply Vessel", "Support Jack Up", "Tank Barge", "Tank Cleaning Vessel", "Tank-Cleaning Vessel", "Tanker", "Tanker (HAZ-A)", "Tanker (HAZ-B)", "Tanker (HAZ-C)", "Tanker (HAZ-D)", "Tanker - Hazard A (Major)", "Tanker - Hazard B", "Tanker - Hazard C (Minor)", "Tanker - Hazard D (Recognizable)", "Tankers", "Tender", "Timber Carrier", "Torpedo Recovery Vessel", "Towing Vessel", "Towing vessel (tow>200)", "Trailing Suction Hopper Dredger", "Training Ship", "Trans Shipment Vessel", "Trawler", "Trenching Support Vessel", "Tug", "Tug/Ice Breaker", "Tug/Supply Vessel", "Unknown", "Unknown (HAZ-A)", "Unknown (HAZ-B)", "Unknown (HAZ-C)", "Unknown (HAZ-D)", "unknown type", "Unspecified", "Urea Carrier", "Utility Vessel", "Vegetable Oil Tanker", "Vehicles Carrier", "Vessel (function unknown)", "Waste Disposal Vessel", "Water Tanker", "Well Stimulation Vessel", "Whale Catcher", "Whaler", "WIG", "WIG (HAZ-A)", "WIG (HAZ-B)", "WIG (HAZ-C)", "WIG (HAZ-D)", "Wind Turbine Vessel", "Wine Tanker", "Wing In Grnd", "Wing In Ground Effect Vessel", "Wood Chips Carrier", "Work Pontoon", "Work Vessel", "Work/Repair Vessel", "Yacht" ] ``` *** ## Accepted Values for `country` 273 accepted values. Matching is case-insensitive. ```json theme={null} [ "Adelie Land", "Afghanistan", "Alaska", "Albania", "Algeria", "American Samoa", "Andorra", "Angola", "Anguilla", "ANTARCTICA", "Antigua & Barbuda", "ANTIGUA AND BARBUDA", "Argentina", "Armenia", "Aruba", "Ascension Island", "Australia", "Austria", "Azerbaijan", "Azores", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium", "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", "Bosnia & Herzegovina", "BOSNIA AND HERZEGOVINA", "Botswana", "Brazil", "British Virgin Islands", "Brunei", "Bulgaria", "Burkina Faso", "Burundi", "CABO VERDE", "Cambodia", "Cameroon", "Canada", "Cape Verde", "Cayman Islands", "Central Africa Rep (CAR)", "CENTRAL AFRICAN REPUBLIC", "Chad", "Chile", "China", "Christmas Island", "Cocos Islands", "COCOS KEELING ISLANDS", "Colombia", "Comoros", "Congo", "Cook Islands", "Costa Rica", "Cote d'Ivoire", "Croatia", "Crozet Archipelago", "Cuba", "Curacao", "Cyprus", "Czech Rep", "CZECH REPUBLIC", "DEMOCRATIC PEOPLES REPUBLIC OF KOREA", "DEMOCRATIC REPUBLIC OF CONGO", "Denmark", "Djibouti", "Dominica", "Dominican Rep", "DOMINICAN REPUBLIC", "DPR Korea", "DR Congo", "East Timor", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea", "Estonia", "ESWATINI", "Ethiopia", "Faeroe Islands", "Falkland Islands", "FAROE ISLANDS", "Fiji", "Finland", "France", "French Polynesia", "FRENCH SOUTHERN TERRITORIES", "Gabon", "Gambia", "Georgia", "Germany", "Ghana", "Gibraltar", "Greece", "Greenland", "Grenada", "Guadeloupe", "Guatemala", "Guiana", "Guinea", "GUINEA BISSAU", "Guinea-Bissau", "Guyana", "Haiti", "HOLY SEE", "Honduras", "Hong Kong", "Hungary", "Iceland", "India", "Indonesia", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica", "Japan", "Jordan", "Kazakhstan", "Kenya", "Kerguelen Islands", "Kiribati", "Korea", "Kuwait", "Kyrgyz Rep", "KYRGYZSTAN", "Laos", "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg", "Macao", "Macedonia", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", "Martinique", "Mauritania", "Mauritius", "Mexico", "Micronesia", "Moldova", "Monaco", "Mongolia", "Montenegro", "Montserrat", "Morocco", "Mozambique", "Myanmar", "N. Mariana Isl", "Namibia", "Nauru", "Nepal", "Netherlands", "New Caledonia", "New Zealand", "Nicaragua", "Niger", "Nigeria", "Niue", "NORTH MACEDONIA", "NORTHERN MARIANA ISLANDS", "Norway", "Oman", "Pakistan", "Palau", "Palestine", "Panama", "Papua New Guinea", "Paraguay", "Peru", "Philippines", "PITCAIRN", "Pitcairn Island", "Poland", "Portugal", "Portugal (Madeira)", "Puerto Rico", "Qatar", "REPUBLIC OF KOREA", "Reunion", "Romania", "Russia", "Rwanda", "Saint Helena", "SAINT HELENA ASCENSION AND TRISTAN DA CUNHA", "SAINT KITTS AND NEVIS", "SAINT LUCIA", "SAINT PIERRE AND MIQUELON", "SAINT VINCENT AND THE GRENADINES", "Samoa", "San Marino", "Sao Tome & Principe", "SAO TOME AND PRINCIPE", "Saudi Arabia", "Senegal", "Serbia", "Seychelles", "Sierra Leone", "Singapore", "Slovakia", "Slovenia", "Solomon Islands", "Somalia", "South Africa", "South Sudan", "Spain", "Sri Lanka", "St Kitts & Nevis", "St Lucia", "St Paul & Amsterdam Isl", "St Pierre & Miquelon", "St Vincent & Grenadines", "Sudan", "Suriname", "Swaziland", "Sweden", "Switzerland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "TIMOR LESTE", "TOGO", "Togolese Rep", "Tonga", "Trinidad & Tobago", "TRINIDAD AND TOBAGO", "Tunisia", "Turkey", "TURKIYE", "Turkmenistan", "Turks & Caicos Isl", "TURKS AND CAICOS ISLANDS", "Tuvalu", "UAE", "Uganda", "Ukraine", "UNITED ARAB EMIRATES", "United Arab Emirates (UAE)", "UNITED KINGDOM", "United Kingdom (UK)", "United States (USA)", "UNITED STATES OF AMERICA", "Unknown", "Uruguay", "US Virgin Islands", "USA", "Uzbekistan", "Vanuatu", "Vatican", "Venezuela", "Vietnam", "Wallis and Futuna", "Yemen", "Zambia", "Zimbabwe" ] ``` These lists are a snapshot of the current database values and are not expected to change. If the backend adds values, this page and the frontend dropdowns need updating together. Alternatively, use the runtime trick described in the 422 section to always reflect the current backend state.