FishNet2 v1 API Help


Services

Default behavior for all services
  • All FishNet2 services provide comma-separated value (csv) formatted output.
    Tab-delimited formatted text is supported with the &fmt=txt parameter (more information).
  • Services will return all rows matching the query parameters.
  • The column names will appear as the first row output. For the Taxa, Providers and Occurrences services, if no occurrences or rows match the query, the 'column headers' row will be the only row returned.
  • Services will return error messages for the following reasons:
    • Missing or incorrect Api Key (more information)
    • Failure to provide at least one of the required query parameters (more information)
    • Missing or incorrectly-formatted WKT provided for the Geometry parameter value (more information)
    • Missing or incorrectly-formatted date value provided for the Date Range parameter (more information)
Taxa service
  • Location:
    http://www.fishnet2.net/api/v1/taxa/
  • Input:
    See the Parameters section, below.
  • Output:
    ScientificName, Num Records
  • Description:
    The Taxa service outputs the scientific names, and the number of occurences of the scientific name matching the query parameters.
    Examples:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&q=larva
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&c=mnhn or usnm
Providers service
  • Location:
    http://www.fishnet2.net/api/v1/providers/
  • Input:
    See the Parameters section, below.
  • Output:
    Institution, InstitutionCode, Num Records
  • Description:
    The Provders service outputs the institution, institution code, and the number of occurences of the institution matching the query parameters.
    Examples:
    • http://www.fishnet2.net/api/v1/providers/?api=MyAPIKey&l=usa
    • http://www.fishnet2.net/api/v1/providers/?api=MyAPIKey&d=1950-1975
OccurrenceCount service
  • Location:
    http://www.fishnet2.net/api/v1/occurrencecount/
  • Input:
    See the Parameters section, below.
  • Output:
    TotRows, No Error, GeoTot
  • Description:
    The OccurrenceCount service outputs the total number of occurrences, query error state, and the total number of occurences that geocode matching the query parameters.
    Examples:
    • http://www.fishnet2.net/api/v1/occurrencecount/?api=MyAPIKey&q=ethanol or EtOH
    • http://www.fishnet2.net/api/v1/occurrencecount/?api=MyAPIKey&p=POLYGON((-93.998292265615 32.615318339629,-92.471192656236 32.606063985828,-92.635987578112 31.235349580893,-90.988038359361 31.19776691287,-90.955079374988 30.395621231989,-93.94336062499 30.386144489302,-93.998292265615 32.615318339629))
Occurrence service
  • Location:
    http://www.fishnet2.net/api/v1/occurrence/
  • Input:
    See the Parameters section and the Additional Occurrence parameters section, below.
  • Default output:
    InstitutionCode, CollectionCode, CatalogNumber, IndividualCount, ScientificName, Family, PreparationType, Tissues, Latitude, Longitude, CoordinateUncertaintyInMeters, HorizontalDatum, Country, StateProvince, County, Island, IslandGroup, Locality, VerbatimElevation, VerbatimDepth, YearCollected, MonthCollected, DayCollected, Collector, GeorefMethod, LatLongComments, BasisOfRecord, Remarks, DateLastModified
  • Description:
    The Occurrence service outputs the occurrence data matching the query parameters.
    Example:
    • http://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&t=notropis venustus&l=louisiana
AvailableMaps service
  • Location:
    http://www.fishnet2.net/api/v1/availablemaps/
  • Input:
    • As with all services, the API parameter is required.
    • All other parameters are optional. A list of all of the maps and the associated metadata will be provided by default.
    • The q= parameter can be used to query for selected maps.
      Example:
      • This query will return all of the maps for May or June
        http://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&q=May or June
      • This query will return all of the maps related to the Federal Fishery Closures
        http://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&q=Fishery Closure
    • When returning a list, the format parameter (fmt=) and attachment parameters (att=) are available (see here for details and examples).
    • Instead of returning a list, use the download parameter d= with a map name to download a KML file corresponding to that FileName.
      Example:
      • http://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&d=FisheryClosure_050210
      • http://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&d=NESDIS Anomaly RS2 6-24-10
      You will receive an error message if the FileName does not exist.
  • Default output:
    MapID, DisplayName, FileName, MapDescription
  • Description:
    The Available Maps service outputs metadata about the maps currently available for querying against in our database with the &m= parameter, or it outputs a map in KML format.
    Example:
    • http://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey
    • http://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&q=May or June
    • http://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&d=FisheryClosure_053110
Locations service
  • Location:
    http://www.fishnet2.net/api/v1/locations/
  • Input:
    See the Parameters section, below.
  • Default output:
    Country, StateProvince, County, Locality, Latitude, Longitude, Num Records
  • Description:
    The Provders service outputs the institution, institution code, and the number of occurences of the institution matching the query parameters. The Locations service outputs the country, state/province, county, locality, latitude, longitude and the number of occurences for that location the query parameters.
    Example:
    • http://www.fishnet2.net/api/v1/locations/?api=MyAPIKey&t=notropis venustus&d=2000-2010

Parameters

Required API Key Parameter
  • API Key: api=
    REQUIRED:
    All FishNet2 services require the 'api' parameter. Without a valid 'api' parameter, your query will not be processed. Nelson Rios at nrios@tulane.edu for a key.
    Example:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey

Query parameters for all services

REQUIRED:
At least one of the following parameters is required, though any or all are permitted in a single query.
  • Taxon: t=
    Use this to search scientific and family names. It supports the 'OR' operator, permitting the search of multiple taxa with one query.
    Examples:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=notropis
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=notropis or nezumia
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=Blenniidae
  • Location: l=
    Use this to search country, continent, county, ocean, island, state, province and locality. It supports the 'OR' operator, permitting the search of multiple locations with one query.
    Examples:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&l=usa
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&l=alabama or gulf of mexico
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=Africa
    You may also restrict your search to the continent/ocean, country, state/province and/or county fields by using the continentocean, country, stateprovince and/or county delimiters in the following format:
    [delimiter]:[search term] - (e.g. county:orleans)
    Multiple delimiters/search term combinations should be separated with semicolons:
    [delimiter]:[search term];[delimiter]:[search term] - (e.g. stateprovince:illinois;county:cook)
    Example:
    • This query will return occurrences matching the state of Mississippi, and not occurrences outside of that state of Mississippi that happen to have the word 'Mississippi' (e.g. 'Mississippi River') in the Locality field.
      http://www.fishnet2.net/api/v1/locations/?api=MyAPIKey&l=stateprovince:Mississippi
    • This query will return all occurrences that have been collected in Grand County, Utah.
      http://www.fishnet2.net/api/vi/locations/?api=MyAPIKey&l=stateprovince:Utah;county:Grand
  • Catalog Number/Institution Code: c=
    Use this to search by Catalog Number and/or Institution Code. It supports the 'OR' operator, permitting the search of multiple Catalog Number and/or Institution Code combinations with one query.
    Examples:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&c=TU 1
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&c=mnhn or usnm
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&c=ku 29288 or tu 66762
  • Date Range: d=
    Use this to search by the year or years the occurrence was collected. Date Ranges must be in yyyy-yyyy format.
    Examples:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&d=2000-2000
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&d=1950-1975
  • Other: q=
    Use this to search for terms of interest that may be in the remarks, notes, scientific name, collector, preparation type, location fields or elsewhere in the occurrence. It supports the 'OR' operator, permitting the search of multiple terms with one query.
    Examples:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&q=larva
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&q=ethanol or EtOH
  • Geometry: p=
    Use this to define a geometric query in well-known text (WKT) format. Input polygons are limited to 250 vertices or 10,000 characters. Note that the Map parameter and the Geometry paramter (see below) are mutually exclusive. If both are submitted, the Map parameter will be ignored.
    Example:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&p=POLYGON((-93.998292265615 32.615318339629,-92.471192656236 32.606063985828,-92.635987578112 31.235349580893,-90.988038359361 31.19776691287,-90.955079374988 30.395621231989,-93.94336062499 30.386144489302,-93.998292265615 32.615318339629))
  • Map: m=
    Use this to query within a geographic area defined by one of the available maps. Maps are designated by MapIDs (see AvailableMaps for a list of valid MapIDs). Note that the Map parameter and the Geometry paramter (see above) are mutually exclusive. If both are submitted, the Map parameter will be ignored.
    Example:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&m=14
OPTIONAL:
The following parameters are optional, and may be added to any query that also includes the required parameters.
  • Format: fmt=
    Valid values are 'txt' (tab-delimited text) or 'csv' (comma-separated values). If no format parameter is provided, the default value is 'csv'.
    Example:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=notropis venustus&l=louisiana&fmt=txt
  • Attachment: att=
    Valid values are '1' or '0' (zero). If no attachment parameter is provided, the default value is '0'. When &att=1, the service appends a file name to the response header. This will allow enabled clients (e.g. web browsers) to recieve the search results as a file attachment.
    Example:
    • http://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=notropis venustus&l=louisiana&fmt=txt&att=1

Additional parameters for the Occurrence service

OPTIONAL:
The following are optional parameters for the Occurrence service, and may be added to any query that also includes the required parameters.
  • Columns: cols=
    Use this parameter, followed by a comma-delimited list of column names, to specify the columns and order of columns to be returned by your search query. All columns are returned by default, in the sequence shown below.
    Example:
    • http://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&l=louisiana&cols=Latitude,Longitude,Family,ScientificName,IndividualCount,Remarks
    Valid column names (in default order):
    • InstitutionCode, CollectionCode, CatalogNumber, IndividualCount, ScientificName, Family, PreparationType, Tissues, Latitude, Longitude, CoordinateUncertaintyInMeters, HorizontalDatum, Country, StateProvince, County, Island, IslandGroup, Locality, VerbatimElevation, VerbatimDepth, YearCollected, MonthCollected, DayCollected, Collector, GeorefMethod, LatLongComments, BasisOfRecord, Remarks, DateLastModified
  • Number of occurrences: num=
    Use this parameter to limit the number of occurrences returned by the service. A maximum value of 10000 is permitted for any single query. By default all results will be returned, even if the number of occurrences returned exceeds 10,000.
    Examples:
    • This query will return the first 10 results
      http://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&l=louisiana&fmt=txt&num=10
    • This query will return 1000 results, beginning with the 1000th record (see below)
      http://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&c=tu&set=1000&num=1000
  • Start value: set=
    For any given search, results will always be returned in the same order. Use this parameter to take control of paging by specifying the first occurrence to be returned for the set of search results. By default, the first occurrence is always set to 1. If a value is specified for this parameter that exceeds the number of records in the result set, no occurrences will be returned.
    Examples:
    • This query will return all results beginning with the 10th
      http://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&d=2010-2011&fmt=txt&set=10
    • This query will return 1000 results, beginning with the first record - i.e. occurrences 1-1000
      http://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&c=tu&num=1000&set=1
    • This query will return 1000 results, beginning with the 1001st record - i.e. occurrences 1001-2000
      http://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&c=tu&num=1000&set=1001
  • No Column Headers: hdr=0
    Set this value to '0' to return results without the column names included as part of the result set. Valid values are '1' or '0' (zero). By default the value is set to '1', and column names will always be included as the first row returned by a result set, even for queries that do not return any results.
    Example:
    • http://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&c=tu&set=1000&num=1000&hdr=0