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 1 of the API is:

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

At present, the first service offered through this API is to provide access to specimen observation records. 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 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

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, year, month, day, recordType, spatialAcc, yrAcc, refID, status, callback, api_key

Query Parameters

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

Paramter	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, Plants, 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 two-letter U.S. Postal Service abbreviation of the U.S. state in which the occurrence was recorded
county	The full county name in which the occurrence was recorded
huc8	The eight-digit Hydrologic Unit Code, as found in the Watershed Boundary Dataset. Interpreted as a string, with leading "0" removed
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
api_key	User-specific API key. Requests lacking an API key will be limited to a maximum of 100 records. Please contact Pam Fuller to discuss receiving a key

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 Pam Fuller or Matt Neilson. To report any bugs or technical issues, please contact Matt Neilson.

Funding for development of the API was provided by the U.S. Geological Survey Community for Data Integration.

---