NAS Web Services API

Introduction

The USGS Nonindigenous Aquatic Species (NAS) Web Services API provides automatic, machine-readable access to spatially-referenced observation data on introduced aquatic species held within the NAS Database. The base URL for version 2 of the API is:

  • http://nas.er.usgs.gov/api/v2

At present, the services offered through this API are to provide access to specimen observation records and lists of species present within the NAS Database. Future versions of the API may contain additional services.

For a complete description of the NAS Database, please review our project summary and metadata.


Specimen Records

This API provides allows for the retrieval of a single NAS specimen occurrence record.

Resource URL Response Description
/occurrence/{key} Example Get the details for a single specimen occurrence record, where {key} indicates the specimen occurrence ID within the NAS Database


Specimen Searching

The specimen record search API provides a mechanism to query for specimen occurrence records within the USGS NAS Database.

Resource URL Response Description Parameters
/occurrence/search Example Full search across all NAS occurrence records. Results are ordered by species ID and occurrence record ID species_ID, group, family, genus, species, state, county, huc8, huc10, huc12, year, month, day, recordType, spatialAcc, yrAcc, refID, status, callback, format


Specimen Query Parameters

The following parameters are allowed for refining queries with the Search API:

Parameter Description
species_ID A numeric identifier given to a single taxon (species or subspecies) within the USGS NAS database
group A vernacular higher taxonomic identifier, generally corresponding to the class or ordinal level. Possible values: Amphibians-Frogs, Amphibians-Salamanders, Annelids-Oligochaetes, Bryozoans, Coelenterates-Hydrozoans, Crustaceans-Amphipods, Crustaceans-Cladocerans, Crustaceans-Copepods, Crustaceans-Crabs, Crustaceans-Crayfish, Crustaceans-Isopods, Crustaceans-Mysids, Crustaceans-Shrimp, Entoprocts, Fishes, Mammals, Mollusks-Bivalves, Mollusks-Cephalopods, Mollusks-Gastropods, Reptiles-Crocodilians, Reptiles-Lizards, Reptiles-Snakes, Reptiles-Turtles, Rotifers
family A taxonomic identifier for the family level (e.g., Cyprinidae)
genus A taxonomic identifier for the genus level (e.g., Cyprinus)
species A taxonomic identifier for the species level (e.g., carpio)
state The ISO 3166-2 subdivision code of the U.S. state or territory where the occurrence was recorded
county The full county name where the occurrence was recorded
huc8 The eight-digit Hydrologic Unit Code, as found in the Watershed Boundary Dataset
huc10 The ten-digit Hydrologic Unit Code, as found in the Watershed Boundary Dataset
huc12 The twelve-digit Hydrologic Unit Code, as found in the Watershed Boundary Dataset
year The four digit year. Supports query over a range by concatenating start and end year with a comma (e.g., year=1990,2000)
month The numeric month of the year, beginning with 1 for January
day The numeric day of the month
recordType General class of the source of information of an occurrence record. One of three possible types:
  • Literature – derived from a citable reference source
  • Personal communication – derived from correspondence between NAS staff and observer
  • Specimen – derived from museum collection records, with an associated traceable physical specimen
spatialAcc The geospatial accuracy of the geographic coordinates of the site associated with the occurrence. One of three potential values:
  • Accurate – geographic coordinates provided in record source; or a precise, unambiguous site description is presented
  • Approximate – approximate geographic location or ambiguous site description
  • Centroid – geographic coordinates are calculated (via GIS) center point of a boundary polygon (e.g., geopolitical administrative unit, watershed)
yrAcc The temporal accuracy of the date of observation associated with the occurrence. One of three potential values:
  • Actual – year indicates actual year of occurrence
  • Estimated – year is best estimation based on information contained within record source
  • Publication year – year is assigned to publication year of record source
refID An identifier of an individual reference within the USGS NAS reference database
status The current status of the introduced population at a location
callback User-defined callback function. Specifying this parameter will return query results as JSONP
format Results output format. Use 'naisma' to retrieve data formatted according to the 2018 NAISMA Mapping Standards


Species Records

This API allows for the retrieval of all NAS species records or a single NAS species record.

Resource URL Response Description
/species Example Get the details for all species tracked by the NAS Database.
/species/{key} Example Get the details for a single species record, where {key} indicates the species ID within the NAS Database


Species Searching

The species record search API provides a mechanism to query for species within the USGS NAS database.

Resource URL Response Description Parameters
/species/search Example Full search across all species tracked by the NAS Database. Results are ordered by species ID group, family, genus, species, native_exotic, fresh_marine_brackish, callback


Species Query Parameters

The following parameters are allowed for refining queries with the Search API:

Parameter Description
group A vernacular higher taxonomic identifier, generally corresponding to the class or ordinal level. Possible values: Amphibians-Frogs, Amphibians-Salamanders, Annelids-Oligochaetes, Bryozoans, Coelenterates-Hydrozoans, Crustaceans-Amphipods, Crustaceans-Cladocerans, Crustaceans-Copepods, Crustaceans-Crabs, Crustaceans-Crayfish, Crustaceans-Isopods, Crustaceans-Mysids, Crustaceans-Shrimp, Entoprocts, Fishes, Mammals, Mollusks-Bivalves, Mollusks-Cephalopods, Mollusks-Gastropods, Reptiles-Crocodilians, Reptiles-Lizards, Reptiles-Snakes, Reptiles-Turtles, Rotifers
family A taxonomic identifier for the family level (e.g., Cyprinidae)
genus A taxonomic identifier for the genus level (e.g., Cyprinus)
species A taxonomic identifier for the species level (e.g., carpio)
native_exotic Native or non-native to United States. Possible values: Native, Exotic, Cryptogenic, Hybrid
fresh_marine_brackish The salinty level for the species location. Possible values: Fresh, Marine, Brackish
callback User-defined callback function. Specifying this parameter will return query results as JSONP


Paging Requests

The occurrence search API supports paging of query results, using the following parameters:

Parameter Description
limit Controls the number of results returned in each page.
offset Controls the offset for the search results, to get the appropriate page. For example, if a particular query string yields 100 records, adding &limit=10&offset=10 will return a page of results containg records 11 through 20

For more information or questions about the API, please contact Matt Neilson.

 

Disclaimer:

The data represented on this site vary in accuracy, scale, completeness, extent of coverage and origin. It is the user's responsibility to use these data consistent with their intended purpose and within stated limitations. We highly recommend reviewing metadata files prior to interpreting these data.

Citation information: U.S. Geological Survey. [2024]. Nonindigenous Aquatic Species Database. Gainesville, Florida. Accessed [4/19/2024].

Contact us if you are using data from this site for a publication to make sure the data are being used appropriately and for potential co-authorship if warranted.

For general information and questions about the database, contact Wesley Daniel. For problems and technical issues, contact Matthew Neilson.