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.


Accessibility FOIA Privacy Policies and Notices

Take Pride in America logoU.S. Department of the Interior | U.S. Geological Survey
URL: https://nas.er.usgs.gov
Page Contact Information: Pam Fuller - NAS Program (pfuller@usgs.gov)
Page Last Modified: Thursday, January 26, 2017

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. [2017]. Nonindigenous Aquatic Species Database. Gainesville, Florida. Accessed [3/25/2017].

Additional information for authors