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 &format=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 include 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 you provided for the Date Range parameter (more information).

Taxa service

  • Location: http://www.fishnet2.net/api/v1/taxa/

  • Inputs: See the Parameters section, below.

  • Default 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:
    https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&q=larva
    https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&c=mnhn or usnm

Providers service

  • Location: http://www.fishnet2.net/api/v1/providers/

  • Inputs: See the Parameters section, below.

  • Default Output: Institution, InstitutionCode, Num Records

  • Description: The Taxa service outputs the scientific names, and the number of occurences of the scientific name matching the query parameters.

  • Examples:
    https://www.fishnet2.net/api/v1/providers/?api=MyAPIKey&l=usa
    https://www.fishnet2.net/api/v1/providers/?api=MyAPIKey&d=1950-1975

  • OccurrenceCount service

  • Location: http://www.fishnet2.net/api/v1/occurrencecount/

  • Inputs: See the Parameters section, below.

  • Default 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:
    https://www.fishnet2.net/api/v1/occurrencecount/?api=MyAPIKey&q=ethanol or EtOH
    https://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/

  • Inputs: 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.

  • Examples:
    https://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&t=notropis venustus&l=louisiana

AvailableMaps service

  • Location: http://www.fishnet2.net/api/v1/availablemaps/

  • Inputs:

    • 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.

      Examples:
      This query will return all of the maps for May or June https://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 https://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: https://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&d=FisheryClosure_050210 https://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.

  • Examples:
    https://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey
    https://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&q=May or June
    https://www.fishnet2.net/api/v1/availablemaps/?api=MyAPIKey&d=FisheryClosure_053110

Locations service

  • Location: http://www.fishnet2.net/api/v1/locations/

  • Inputs: See the Parameters section, below.

  • Default output:Country, StateProvince, County, Locality, Latitude, Longitude, Num Records

  • Description:The Providers 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.

  • Examples:
    https://www.fishnet2.net/api/v1/locations/?api=MyAPIKey&t=notropis venustus&d=2000-2010

Parameters

Required API Key Parameter

  • API Key api=:
    All FishNet2 services require the &key parameter. Without a valid &key parameter, your query will not be processed. Yasin Bakis at ybakis@tulane.edu for a key.

    Examples: https://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 can be 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:
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=notropis
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=notropis or nezumia
      https://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:
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&l=usa
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&l=alabama or gulf of mexico
      https://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)

      Examples:
      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. https://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. https://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 Numbers and/or Institution Codes with one query.

      Examples:
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&c=TU 1https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&c=mnhn or usnmhttps://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:
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&d=2000-2000https://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:
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&q=larvahttps://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 parameter (see below) are mutually exclusive. If both are submitted, the Map parameter will be ignored.

      Examples:
      https://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=:
      Records 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 parameter (see above) are mutually exclusive. If both are submitted, the Map parameter will be ignored.

      Examples:
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&m=14

    Optional parameters

    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'.

      Examples:
      https://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.

      Examples:
      https://www.fishnet2.net/api/v1/taxa/?api=MyAPIKey&t=notropis venustus&l=louisiana&fmt=txt&att=1

    Additional parameters for the Occurrence service

    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.

      Examples:
      https://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

      https://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)

      https://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

      https://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

      https://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

      https://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.

      Examples:
      https://www.fishnet2.net/api/v1/occurrence/?api=MyAPIKey&c=tu&set=1000&num=1000&hdr=0