# NOAA Fisheries One Stop Shop

> Read the United States' official fishery statistics from NOAA Fisheries' One Stop Shop: what commercial fishermen landed in each state since 1950 and what it sold for, what recreational anglers kept since 1980, seafood imports and exports by product and country every month, what US processors produced, the Alaska bottom trawl surveys station by station, and the Coast Guard's register of documented vessels. Rank the species landed in a state or the partners the US buys shrimp from, follow a species' landings over ten years, or read the Bering Sea's bottom temperature. No account or API key required.

App · Research & Academia · 11 actions. Web page: https://docs.lodol.com/docs/integrations/noaa-foss

## Actions

### Find a documented vessel

Look up vessels in the Coast Guard's register of documented vessels, the ones of five net tons and more: by name, documentation number, call sign or IMO number, narrowed by kind of vessel and home state. Each comes with its home port, length, tonnage, year built, builder, hull, engine power and whether its documentation is valid and until when.

**Inputs**

- Vessel name (`vessel_name`, text): Words in the vessel's name. Names repeat (there are over a hundred ENDEAVORs), so add a kind of vessel or a home state to narrow it.
- Coast Guard number (`coast_guard_number`, text): The vessel's Coast Guard documentation number, all digits.
- Call sign (`call_sign`, text): The vessel's radio call sign, such as WDE5199.
- IMO number (`imo_number`, text): The vessel's seven-digit International Maritime Organization number.
- Kind of vessel (`service`, text): Only vessels documented for one kind of service, such as commercial fishing. One of: `commercial_fishing` (Commercial fishing vessel), `fish_processing` (Fish processing vessel), `fishing_tender` (Fishing tender), `recreational`, `passenger_inspected` (Passenger, inspected), `passenger_uninspected` (Passenger, uninspected), `passenger_barge` (Passenger barge), `towing` (Towing vessel), `freight_ship` (Freight ship), `freight_barge` (Freight barge), and 7 more.
- Home state (`hail_state`, text): Only vessels whose home port is in one state, as its name or its two letters, such as Alaska or AK.
- How many (`limit`, number): The most vessels to return. Defaults to 25. From 1 to 200. Default: `25`.

**Outputs**

- `count` (number): Rows in 'vessels'
- `more` (true/false): Whether more vessels matched
- `summary` (text): One sentence a workflow can send as it stands
- `vessels` (list): The matching vessels

**Example output**

```json
{
  "count": 1,
  "more": false,
  "summary": "1 documented vessel matches; the first is NORTHWESTERN of SEATTLE.",
  "vessels": [
    {
      "breadthFt": 27.1,
      "builder": "MARINE CONSTRUCTION ...",
      "callSign": "WDE5199",
      "coastGuardNumber": "587816",
      "documentExpires": "2027-08-31",
      "documentIssued": "2026-08-01",
      "documentationStatus": "Valid",
      "grossTons": 194.0,
      "hailPort": "SEATTLE",
      "hailState": "WA",
      "horsepower": 1280.0,
      "hullMaterial": "Steel",
      "imoNumber": "7719179",
      "lengthFt": 101.8,
      "name": "NORTHWESTERN",
      "netTons": 132.0,
      "propulsion": "Diesel",
      "service": "Commercial Fishing Vessel",
      "yearBuilt": 1977
    }
  ]
}
```

### Find a species

Find species in NOAA Fisheries' species list by common or Latin name, with the number FOSS files each under, the name as its data writes it, its family, whether it is finfish or shellfish, its habitat, whether it is protected and whether FOSS reports landings for it. Use it to find the exact species before reading landings.

**Inputs**

- Name (`search`, text, required): A common or Latin name, whole or in part, such as snapper, king crab or Homarus.
- How many (`limit`, number): The most species to return, closest names first. Defaults to 25. From 1 to 200. Default: `25`.

**Outputs**

- `count` (number): Rows in 'species'
- `matches` (number): Species matching in all
- `search` (text)
- `species` (list): The species, closest names first
- `summary` (text): One sentence a workflow can send as it stands

**Example output**

```json
{
  "count": 1,
  "matches": 43,
  "search": "snapper",
  "species": [
    {
      "afsName": "SNAPPER, DOG",
      "family": "Snappers",
      "habitat": "Marine",
      "inLandings": true,
      "kind": "Finfish",
      "level": "Species",
      "name": "Dog snapper",
      "protected": false,
      "scientificName": "Lutjanus jocu",
      "tsn": "168857"
    }
  ],
  "summary": "43 species match 'snapper'; the first is Dog snapper (TSN 168857)."
}
```

### Find traded seafood products

Find the traded products whose names contain a word, such as every salmon product, with their 10-digit tariff codes, NOAA's product group, whether they are food, and what was traded in one year, largest first. Trade is counted by product rather than species, so this is how to find the right name or code to pass to the other trade actions.

**Inputs**

- Product words (`search`, text, required): Words to find in product names, such as salmon, shrimp or crab. The names are the tariff schedule's, like SALMON ATLANTIC FILLET FRESH FARMED.
- Imports or exports (`flow`, text): Which way the seafood went. Re-exports are imports sent on again without being changed. Defaults to imports. One of: `imports`, `exports`, `re_exports` (Re-exports). Default: `imports`.
- Year (`year`, number): The calendar year to count. Defaults to the last one FOSS has all twelve months of. From 1972 to 2100.
- How many (`limit`, number): The most products to return, largest first. Defaults to 25. From 1 to 200. Default: `25`.

**Outputs**

- `count` (number): Rows in 'products'
- `flow` (text)
- `products` (list): The products, largest by value first
- `productsFound` (number): Products matching in all
- `search` (text)
- `summary` (text): One sentence a workflow can send as it stands
- `total` (object): Weight, value and value per kilogram
- `year` (number)

**Example output**

```json
{
  "count": 1,
  "flow": "Imports",
  "products": [
    {
      "category": "Fresh or frozen, fillet/steak, salmon",
      "dollars": 2407013075,
      "dollarsPerKilogram": 12.06,
      "edible": true,
      "htsCode": "0304410010",
      "kilograms": 199598229,
      "product": "SALMON ATLANTIC FILLET FRESH FARMED",
      "sharePercent": 41.2,
      "speciesGroup": "Salmon"
    }
  ],
  "productsFound": 40,
  "search": "salmon",
  "summary": "40 import products named with 'salmon' in 2025; the largest is SALMON ATLANTIC FILLET FRESH FARMED (0304410010) at $2.4 billion.",
  "total": {
    "dollars": 5841812803,
    "dollarsPerKilogram": 11.39,
    "kilograms": 512973948
  },
  "year": 2025
}
```

### Get Alaska survey catch

Read how much of one fish or invertebrate an Alaska bottom trawl survey caught in a year: how many of its hauls caught any, the total weight and count, and its average density per square kilometre over every haul, which is the number scientists track a stock by. Covers the Bering Sea, Gulf of Alaska and Aleutian Islands surveys. Turn on stations to map where it was caught.

**Inputs**

- Species (`species`, text, required): The fish or invertebrate to count. Pick it from the survey's species list, or type its common or Latin name. Snow crab and red king crab are counted by a separate crab survey FOSS does not publish.
- Survey (`survey`, text, required): Which of the Alaska Fisheries Science Center's bottom trawl surveys. The Eastern Bering Sea shelf is surveyed every summer; the Gulf of Alaska and the Aleutian Islands in alternate years. One of: `EBS` (Eastern Bering Sea shelf), `NBS` (Northern Bering Sea), `GOA` (Gulf of Alaska), `AI` (Aleutian Islands), `BSS` (Eastern Bering Sea slope).
- Year (`year`, number): The survey year. Defaults to that survey's most recent one. From 1982 to 2100.
- List every station (`include_stations`, true/false): Also list each station where the species was caught, with its position, depth, bottom temperature and catch, densest first. Off by default. Default: `false`.

**Outputs**

- `densest` (object): The station with the densest catch
- `encounterPercent` (number): Share of hauls that caught it
- `hauls` (number): Hauls the survey made
- `haulsWithCatch` (number): Hauls that caught it
- `meanKgPerKm2` (number): Average catch per km² over every haul, a haul without it counting as zero
- `meanNumberPerKm2` (number)
- `species` (object): 'code', 'name', 'commonName' and 'scientificName'
- `stations` (list): Every station that caught it, densest first, when asked for
- `summary` (text): One sentence a workflow can send as it stands
- `survey` (text)
- `totalCount` (number)
- `totalWeightKg` (number)
- `year` (number)

**Example output**

```json
{
  "densest": {
    "bottomTemperatureC": 3.2,
    "count": 8782,
    "cpueKgPerKm2": 126575.2,
    "cpueNumberPerKm2": 175249.3,
    "date": "2026-07-25",
    "depthM": 109,
    "latitude": 58.00151,
    "longitude": -172.8579,
    "station": "J-25",
    "weightKg": 6342.87
  },
  "encounterPercent": 99.7,
  "hauls": 350,
  "haulsWithCatch": 349,
  "meanKgPerKm2": 11318.41,
  "meanNumberPerKm2": 19322.99,
  "species": {
    "code": 21740,
    "commonName": "walleye pollock",
    "name": "Walleye pollock (Gadus chalcogrammus)",
    "scientificName": "Gadus chalcogrammus"
  },
  "stations": [],
  "summary": "The 2026 Eastern Bering Sea shelf survey made 350 hauls and caught walleye pollock in 349 of them (99.7%): 191,782 kg in all, an average of 11,318.4 kg per square kilometre.",
  "survey": "Eastern Bering Sea shelf",
  "totalCount": 324167,
  "totalWeightKg": 191781.9,
  "year": 2026
}
```

### Get Alaska survey conditions

Read the water an Alaska bottom trawl survey found, year by year: the mean, coldest and warmest bottom temperature, the share of hauls in water below 2 °C (the Bering Sea's cold pool, which decides where fish and crab can live), the surface temperature, depth and dates. Defaults to the last ten survey years.

**Inputs**

- Survey (`survey`, text, required): Which of the Alaska Fisheries Science Center's bottom trawl surveys. The Eastern Bering Sea shelf is surveyed every summer; the Gulf of Alaska and the Aleutian Islands in alternate years. One of: `EBS` (Eastern Bering Sea shelf), `NBS` (Northern Bering Sea), `GOA` (Gulf of Alaska), `AI` (Aleutian Islands), `BSS` (Eastern Bering Sea slope).
- From year (`from_year`, number): The first survey year to include. Defaults to nine years before the last. From 1982 to 2100.
- To year (`to_year`, number): The last survey year to include. Defaults to the most recent. From 1982 to 2100.

**Outputs**

- `count` (number): Rows in 'years'
- `fromYear` (number)
- `summary` (text): One sentence a workflow can send as it stands
- `survey` (text)
- `toYear` (number)
- `years` (list): One row per survey year, oldest first

**Example output**

```json
{
  "count": 1,
  "fromYear": 2017,
  "summary": "Eastern Bering Sea shelf survey: the mean bottom temperature was 1.8 \u00b0C in 2026; warmest year 2019 (4.35 \u00b0C), coldest 2026 (1.8 \u00b0C).",
  "survey": "Eastern Bering Sea shelf",
  "toYear": 2026,
  "years": [
    {
      "coldHaulsPercent": 34.3,
      "firstDay": "2017-06-04",
      "hauls": 376,
      "lastDay": "2017-07-31",
      "maxBottomTemperatureC": 8.2,
      "meanBottomTemperatureC": 2.66,
      "meanDepthM": 81.2,
      "meanSurfaceTemperatureC": 7.99,
      "minBottomTemperatureC": -1.6,
      "year": 2017
    }
  ]
}
```

### Get fishery landings

Read what US fishermen landed, year by year: the pounds brought to the dock and what they sold for, for one species or every species together, in one state, one region or the whole country. Choose recreational to get what anglers kept instead, as weight and number of fish. Defaults to the last ten years NOAA has published, and says how much the value changed and which year was the peak. Figures withheld for confidentiality are counted and never taken for zeros.

**Inputs**

- Species (`species`, text): The species to count. Pick it from the species FOSS reports landings for, or type a common name (American lobster), a Latin name or a species number. Leave empty to add up every species.
- State (`state`, text): Only landings in one state. FOSS reports Florida as two coasts; choose both coasts to add them up. Leave this and Region empty for the whole country. One of: `alabama`, `alaska`, `california`, `connecticut`, `delaware`, `district_of_columbia` (District of Columbia), `florida` (Florida, both coasts), `florida_east` (Florida, Atlantic coast), `florida_west` (Florida, Gulf coast), `georgia`, and 25 more.
- Region (`region`, text): Only landings in one of NOAA Fisheries' regions, instead of one state. New York is counted in both the Middle Atlantic and the Great Lakes. One of: `new_england` (New England), `middle_atlantic` (Middle Atlantic), `south_atlantic` (South Atlantic), `gulf`, `great_lakes` (Great Lakes), `pacific_coast` (Pacific Coast), `alaska`, `hawaii`.
- Commercial or recreational (`sector`, text): Commercial landings, counted since 1950 with what they sold for, or recreational catch, counted since 1980 as the weight and number of fish anglers kept, which has no dollar value. Defaults to commercial. One of: `commercial`, `recreational`. Default: `commercial`.
- From year (`from_year`, number): The first year to include. Defaults to nine years before the last, so ten years in all. From 1950 to 2100.
- To year (`to_year`, number): The last year to include. Defaults to the newest year FOSS has, which trails the calendar by a year or more. From 1950 to 2100.

**Outputs**

- `byState` (list): Each state's share of the period, largest first
- `change` (object): From the first year to the last: 'percent' change in value (weight for recreational catch) and the 'peakYear'
- `fromYear` (number)
- `notes` (list): What to know about the figures, such as confidential records
- `place` (text): The state, region or country
- `sector` (text): Commercial or Recreational
- `species` (object): The species: 'name', 'afsName' as FOSS writes it, 'scientificName', 'tsn' and any 'otherTsns' filed under the same name. Null for every species together
- `summary` (text): One sentence a workflow can send as it stands
- `toYear` (number)
- `total` (object): Weight, value, price per pound and fish kept
- `years` (list): One row per year with landings, oldest first

**Example output**

```json
{
  "byState": [],
  "change": {
    "fromYear": 2015,
    "measure": "dollars",
    "peak": 743106667,
    "peakYear": 2021,
    "percent": 7.1,
    "toYear": 2024
  },
  "fromYear": 2015,
  "notes": [],
  "place": "Maine",
  "sector": "Commercial",
  "species": {
    "afsName": "LOBSTER, AMERICAN",
    "name": "American lobster",
    "otherTsns": [],
    "scientificName": "Homarus americanus",
    "tsn": "97314"
  },
  "summary": "American lobster in Maine, commercial: 87.5 million lb worth $538.3 million landed in 2024.",
  "toYear": 2024,
  "total": {
    "dollars": 5039693977,
    "fishCount": null,
    "pounds": 1083594917,
    "pricePerPound": 4.65,
    "withheldRecords": 0
  },
  "years": [
    {
      "dollars": 502564894,
      "fishCount": null,
      "pounds": 122685783,
      "pricePerPound": 4.1,
      "withheldRecords": 0,
      "year": 2015
    }
  ]
}
```

### Get processed seafood production

Read what US seafood processors produced each year, from NOAA's annual survey of every processor: fillets, steaks, fish sticks and portions, breaded shrimp, canned seafood, meal and oil, product by product, in pounds and dollars. Narrow it to a kind of product or a species. Defaults to the last ten years.

**Inputs**

- Kind of product (`product_type`, text): Only one kind of processed product. Leave empty for them all. One of: `fillets`, `steaks`, `portions` (Fish portions), `sticks` (Fish sticks), `breaded_shrimp` (Breaded shrimp), `canned`, `meal` (Fish meal), `oil` (Fish oil).
- Product (`product`, text): Only products whose name contains these words, such as salmon, tuna or pollock. Leave empty for every product.
- From year (`from_year`, number): The first year to include. Defaults to nine years before the last, so ten years in all. From 1950 to 2100.
- To year (`to_year`, number): The last year to include. Defaults to the newest year FOSS has, which trails the calendar by a year or more. From 1950 to 2100.

**Outputs**

- `count` (number): Rows in 'products'
- `fromYear` (number)
- `product` (text)
- `productType` (text)
- `products` (list): Each product each year, newest and largest first
- `summary` (text): One sentence a workflow can send as it stands
- `toYear` (number)
- `years` (list): The products added up by year, oldest first

**Example output**

```json
{
  "count": 1,
  "fromYear": 2020,
  "product": "tuna",
  "productType": "Canned",
  "products": [
    {
      "dollars": 335758000,
      "pounds": 174728000,
      "pricePerPound": 1.92,
      "product": "Tuna, lightmeat chunk",
      "productType": "Canned",
      "year": 2024
    }
  ],
  "summary": "US canned seafood matching 'tuna', 2024: 310.9 million lb worth $749.8 million.",
  "toYear": 2024,
  "years": [
    {
      "dollars": 860029000,
      "pounds": 393872000,
      "pricePerPound": 2.18,
      "year": 2020
    }
  ]
}
```

### Get seafood imports or exports

Read US seafood imports or exports over a stretch of months: the weight, the value and the value per kilogram, month by month, with the ten largest countries and products. Narrow it to a product (shrimp, salmon fillet, a tariff code) and a country. Defaults to imports over the latest twelve months the Census Bureau has published, which trail by about two months.

**Inputs**

- Imports or exports (`flow`, text): Which way the seafood went. Re-exports are imports sent on again without being changed. Defaults to imports. One of: `imports`, `exports`, `re_exports` (Re-exports). Default: `imports`.
- Product (`product`, text): Only products whose name contains these words, such as shrimp, salmon fillet or tuna, or one 10-digit tariff code. Trade is counted by product rather than species; Find traded seafood products shows the names. Leave empty for all seafood.
- Country (`country`, text): Only trade with one country, the source of imports or the destination of exports. Leave empty for every country. One of: `ALBANIA`, `ALGERIA`, `ANGUILLA`, `ANTIGUA & BARBUDA`, `ARGENTINA`, `ARMENIA`, `ARUBA`, `AUSTRALIA`, `AUSTRIA`, `AZERBAIJAN`, and 178 more.
- From month (`from_month`, text): The first month to include, such as 2025-01. Defaults to eleven months before the last, so a year in all.
- To month (`to_month`, text): The last month to include, such as 2025-12. Defaults to the newest month FOSS has, usually two months ago.

**Outputs**

- `country` (text): The country, if one was chosen
- `flow` (text): Imports, Exports or Re-exports
- `fromMonth` (text): YYYY-MM
- `months` (list): One row per month, oldest first
- `notes` (list): What to know about the figures, such as confidential records
- `product` (text): The product words, if any
- `records` (number): Trade records added up
- `summary` (text): One sentence a workflow can send as it stands
- `toMonth` (text): YYYY-MM
- `topCountries` (list): The ten largest partners by value
- `topProducts` (list): The ten largest products by value, with tariff codes
- `total` (object): Weight, value and value per kilogram

**Example output**

```json
{
  "country": "Chile",
  "flow": "Imports",
  "fromMonth": "2025-01",
  "months": [
    {
      "dollars": 262249353,
      "dollarsPerKilogram": 13.41,
      "kilograms": 19560944,
      "month": "2025-01"
    }
  ],
  "notes": [],
  "product": "salmon",
  "records": 759,
  "summary": "Imports of 'salmon' with Chile, 2025-01 to 2025-12: 226.6 million kg worth $2.6 billion.",
  "toMonth": "2025-12",
  "topCountries": [
    {
      "country": "Chile",
      "dollars": 2620436919,
      "dollarsPerKilogram": 11.56,
      "kilograms": 226601017,
      "sharePercent": 100.0
    }
  ],
  "topProducts": [
    {
      "dollars": 1546991828,
      "dollarsPerKilogram": 11.11,
      "htsCode": "0304410010",
      "kilograms": 139298476,
      "product": "SALMON ATLANTIC FILLET FRESH FARMED",
      "sharePercent": 59.0
    }
  ],
  "total": {
    "dollars": 2620436919,
    "dollarsPerKilogram": 11.56,
    "kilograms": 226601017
  }
}
```

### Rank seafood trading partners

Rank the countries the US bought seafood from, or sold it to, in one calendar year, by value or by weight, with each country's continent, price per kilogram and share. Name a product to rank the partners for it alone, such as shrimp. Defaults to imports in the last full year.

**Inputs**

- Imports or exports (`flow`, text): Which way the seafood went. Re-exports are imports sent on again without being changed. Defaults to imports. One of: `imports`, `exports`, `re_exports` (Re-exports). Default: `imports`.
- Product (`product`, text): Only products whose name contains these words, such as shrimp, salmon fillet or tuna, or one 10-digit tariff code. Trade is counted by product rather than species; Find traded seafood products shows the names. Leave empty for all seafood.
- Year (`year`, number): The calendar year to count. Defaults to the last one FOSS has all twelve months of. From 1972 to 2100.
- Rank by (`rank_by`, text): Rank by what the seafood was worth, or by its weight. Defaults to value. One of: `value` (Value in dollars), `weight` (Weight in kilograms). Default: `value`.
- How many (`limit`, number): The most rows to return, from the top. Defaults to 20. From 1 to 200. Default: `20`.

**Outputs**

- `count` (number): Rows in 'countries'
- `countries` (list): The countries, top first
- `flow` (text)
- `notes` (list): What to know about the figures, such as confidential records
- `partners` (number): Countries traded with in all
- `product` (text)
- `rankedBy` (text)
- `summary` (text): One sentence a workflow can send as it stands
- `total` (object): Weight, value and value per kilogram
- `year` (number)

**Example output**

```json
{
  "count": 1,
  "countries": [
    {
      "continent": "Asia",
      "country": "India",
      "dollars": 2409774533,
      "dollarsPerKilogram": 8.2,
      "kilograms": 293977232,
      "rank": 1,
      "sharePercent": 36.1
    }
  ],
  "flow": "Imports",
  "notes": [],
  "partners": 51,
  "product": "shrimp",
  "rankedBy": "Value in dollars",
  "summary": "Imports of 'shrimp' in 2025, by value: India $2.4 billion; Ecuador $1.7 billion; Indonesia $979.6 million.",
  "total": {
    "dollars": 6666527182,
    "dollarsPerKilogram": 8.46,
    "kilograms": 787998785
  },
  "year": 2025
}
```

### Rank the species landed

Rank the species landed in a state, a region or the whole country in one year, by what they sold for, by weight, or for recreational catch by the number of fish kept. Each comes with its share of the total, and the landings pooled for confidentiality are reported beside the ranking rather than ranked as a species. Defaults to the newest year NOAA has.

**Inputs**

- State (`state`, text): Only landings in one state. FOSS reports Florida as two coasts; choose both coasts to add them up. Leave this and Region empty for the whole country. One of: `alabama`, `alaska`, `california`, `connecticut`, `delaware`, `district_of_columbia` (District of Columbia), `florida` (Florida, both coasts), `florida_east` (Florida, Atlantic coast), `florida_west` (Florida, Gulf coast), `georgia`, and 25 more.
- Region (`region`, text): Only landings in one of NOAA Fisheries' regions, instead of one state. New York is counted in both the Middle Atlantic and the Great Lakes. One of: `new_england` (New England), `middle_atlantic` (Middle Atlantic), `south_atlantic` (South Atlantic), `gulf`, `great_lakes` (Great Lakes), `pacific_coast` (Pacific Coast), `alaska`, `hawaii`.
- Commercial or recreational (`sector`, text): Commercial landings, counted since 1950 with what they sold for, or recreational catch, counted since 1980 as the weight and number of fish anglers kept, which has no dollar value. Defaults to commercial. One of: `commercial`, `recreational`. Default: `commercial`.
- Year (`year`, number): The year to rank. Defaults to the newest year FOSS has. From 1950 to 2100.
- Rank by (`rank_by`, text): What to rank by. Defaults to value for commercial landings and to weight for recreational catch, which has no value; number of fish is for recreational catch only. One of: `value` (Value in dollars), `weight` (Weight in pounds), `fish` (Number of fish (recreational)).
- How many (`limit`, number): The most rows to return, from the top. Defaults to 20. From 1 to 200. Default: `20`.

**Outputs**

- `count` (number): Rows in 'species'
- `notes` (list): What to know about the figures, such as confidential records
- `place` (text)
- `rankedBy` (text)
- `sector` (text)
- `species` (list): The species, top first
- `speciesLanded` (number): Species landed in all
- `summary` (text): One sentence a workflow can send as it stands
- `total` (object): Weight, value, price per pound and fish kept
- `withheld` (object): Landings pooled as withheld for confidentiality, not ranked
- `year` (number)

**Example output**

```json
{
  "count": 1,
  "notes": [
    "1067 of 3122 species records have their weight or value withheld for confidentiality. Those landings are pooled into each state's 'withheld for confidentiality' row, which the totals include, so the totals are whole but some species' own figures are low."
  ],
  "place": "United States",
  "rankedBy": "Value in dollars",
  "sector": "Commercial",
  "species": [
    {
      "afsName": "LOBSTER, AMERICAN",
      "dollars": 720403763,
      "fishCount": null,
      "isGroup": false,
      "pounds": 113485081,
      "pricePerPound": 6.35,
      "rank": 1,
      "scientificName": "Homarus americanus",
      "sharePercent": 14.7,
      "species": "American lobster",
      "tsn": "97314",
      "withheldRecords": 2
    }
  ],
  "speciesLanded": 925,
  "summary": "Top commercial species in the United States in 2024 by value: American lobster $720.4 million; Walleye pollock $432.5 million; Sea scallop $332.0 million.",
  "total": {
    "dollars": 4909478386,
    "fishCount": null,
    "pounds": 7681642150,
    "pricePerPound": 0.64,
    "withheldRecords": 1067
  },
  "withheld": {
    "dollars": 166725823,
    "fishCount": null,
    "pounds": 141873708,
    "pricePerPound": 1.18,
    "withheldRecords": 0
  },
  "year": 2024
}
```

### Rank the states landing a species

Find where one species is landed: every state that landed it in one year, ranked by what it sold for or by weight, with each state's region and share of the national total. Choose recreational to rank the states whose anglers kept the most. Defaults to the newest year NOAA has.

**Inputs**

- Species (`species`, text, required): The species to look up. Pick it from the species FOSS reports landings for, or type a common name (American lobster), a Latin name or a species number.
- Commercial or recreational (`sector`, text): Commercial landings, counted since 1950 with what they sold for, or recreational catch, counted since 1980 as the weight and number of fish anglers kept, which has no dollar value. Defaults to commercial. One of: `commercial`, `recreational`. Default: `commercial`.
- Year (`year`, number): The year to rank. Defaults to the newest year FOSS has. From 1950 to 2100.
- Rank by (`rank_by`, text): What to rank by. Defaults to value for commercial landings and to weight for recreational catch, which has no value; number of fish is for recreational catch only. One of: `value` (Value in dollars), `weight` (Weight in pounds), `fish` (Number of fish (recreational)).

**Outputs**

- `count` (number): Rows in 'states'
- `notes` (list): What to know about the figures, such as confidential records
- `rankedBy` (text)
- `sector` (text)
- `species` (object): The species: 'name', 'afsName' as FOSS writes it, 'scientificName', 'tsn' and any 'otherTsns' filed under the same name
- `states` (list): The states, top first
- `summary` (text): One sentence a workflow can send as it stands
- `total` (object): Weight, value, price per pound and fish kept
- `year` (number)

**Example output**

```json
{
  "count": 1,
  "notes": [
    "2 of 10 records have their weight or value withheld for confidentiality, so the totals are a floor rather than the whole."
  ],
  "rankedBy": "Value in dollars",
  "sector": "Commercial",
  "species": {
    "afsName": "LOBSTER, AMERICAN",
    "name": "American lobster",
    "otherTsns": [],
    "scientificName": "Homarus americanus",
    "tsn": "97314"
  },
  "states": [
    {
      "dollars": 538275859,
      "fishCount": null,
      "pounds": 87535403,
      "pricePerPound": 6.15,
      "rank": 1,
      "region": "New England",
      "sharePercent": 74.7,
      "state": "Maine",
      "withheldRecords": 0
    }
  ],
  "summary": "American lobster, commercial, 2024: Maine $538.3 million; Massachusetts $115.7 million; New Hampshire $53.0 million.",
  "total": {
    "dollars": 720403763,
    "fishCount": null,
    "pounds": 113485081,
    "pricePerPound": 6.35,
    "withheldRecords": 2
  },
  "year": 2024
}
```