Web Services Integration

Web Service URL

The NatureServe Surveyor web service is called via the following URL:

https://surveyor.natureserve.org/surveyorws/eoWebService

Note that SSL security is used (via https) and that parameters must be supplied in order for the Surveyor web service to function correctly—simply browsing to the above URL will produce ‘Missing parameter’ error messages.

Surveyor Web Service Input Parameters

You or your application will call the NatureServe Surveyor Web Service by building a URL that will contain the following input parameters. This web service will use standard REST methods to capture the input parameters listed below, where they are either appended to the URL for GET requests, or placed in the body of the request for POST requests. Any parameters supplied in addition to those listed will be ignored.

Parameter

Description

username

A user’s email address will be used as their unique username

password

A user-established password

subscriptionID

The unique ID for the subscription being used to access this web service. This can be found as the number after “subscriptions” in your subscription’s unique URL. For example, if the unique URL is:

https://surveyor.natureserve.org/subscriptions/12347309921

then the subscriptionID is 12347309921.

areaOfInterestType

A code indicating the type of area of interest being submitted, where the type must be one of the following values:

  • county
  • huc8
  • quad
  • polygon

areaOfInterest

 

for types:
FIPS County Code
USGS 8-digit HUC
USGS 7.5’ quad

If areaOfInterestType is not equal to polygon, this parameter must contain a single code from the list below for the user’s area of interest:

  • FIPS county code
  • USGS 8-digit HUC
  • USGS 7.5’ quad code

An invalid code will result in an error message.

areaOfInterest

 

for type:
Polygon – GML

If areaOfInterestType is equal to polygon, this parameter must contain either a GML Version 3.1.1 polygon element, or a KML document containing a polygon. For polygons coded in GML, the details are as follows:

An error message will be generated if the polygon falls completely outside the service coverage area.

A GML polygon must have the following characteristics:

For example:

<Polygon xmlns="http://www.opengis.net/gml">

<exterior>

<LinearRing>

<posList>XY coordinate pairs</posList>

</LinearRing>

</exterior>

</Polygon>

The syntactical validity of the GML is checked. This includes the xml namespace used, which must resolve to http://www.opengis.net/gml, as shown in the above example. Here, the xmlns attribute translates as “all elements within this Polygon element (and including the Polygon element itself) belong to the namespace ‘http://www.opengis.net/gml’.”

areaOfInterest

 

for type:
Polygon - KML

If areaOfInterestType is equal to polygon, this parameter must contain either a GML Version 3.1.1 polygon element, or a KML document containing a polygon. For polygons coded in KML, the details are as follows.

An error message will be generated if the polygon falls completely outside the service coverage area.

A KML polygon must have the following characteristics:

  • One exterior (outer boundary)
  • Area greater than or equal to 2.6 square kilometers

The polygon may be supplied as a standalone element, for example:

<Polygon xmlns="http://www.opengis.net/kml/2.2">

<outerBoundaryIs>

<LinearRing>

<coordinates>X,Y[,Z] coordinates, space separated</coordinates>

</LinearRing>

</outerBoundaryIs>

</Polygon>

The polygon may also appear inside any other kml document, such as one containing a Placemark. In these cases, the first polygon in the document is used.

The syntactical validity of the Polygon is checked. This includes the xml namespace used, which must resolve to http://www.opengis.net/kml/2.2, as shown in the above example. The xmlns attribute translates as “all elements within this Polygon element (and including the Polygon element itself) belong to the namespace ‘http://www.opengis.net/kml/2.2’.”

USESAStatus

This optional filter parameter is used to narrow results down to specific statuses under the U.S. Endangered Species Act. A comma-separated list of following status codes can be supplied:

  • LE – Listed Endangered
  • LT – Listed Threatened
  • PE – Proposed Endangered
  • PT – Proposed Threatened
  • C – Candidate
  • SC – Species of Concern
  • PDL – Proposed for Delisting
  • XE – Essential Experimental Population
  • XN – Non-essential Experimental Population
  • None – A special case meaning “Select only EOs WITHOUT any status”

The codes are not checked for validity and the use of an invalid code will result in an empty result set.

SARAStatus

This optional filter parameter is used to narrow results down to specific statuses under the Species at Risk Act in Canada. A comma-separated list of following status codes can be supplied:

  • E – Endangered
  • T – Threatened
  • SC – Special concern
  • XT – Extirpated
  • None – A special case meaning “Select only EOs WITHOUT any status”

The codes are not checked for validity and the use of an invalid code will result in an empty result set.

 

In general, the syntax of a request is like this:

https://surveyor.natureserve.org/surveyorws/eoWebService?username=<username goes here>&password=<password goes here>&subscriptionID=<subscription ID goes here>&areaOfInterestType=<area of interest type goes here>&areaOfInterest=<area of interest goes here>&USESAStatus=<USESA Status goes here> &SARAStatus = < SARA Status goes here>

The parameters following the question mark are all keywords and do not require a certain position in the URL string. For example:

https://surveyor.natureserve.org/surveyorws/eoWebService?username=mary_doe@EPA.gov& password=be_gr33n &subscriptionID=430101&areaOfInterestType=county&areaOfInterest=35049&USESAStatus=LE,LT

This URL can be sent by your application to the Surveyor web service or you may copy and paste it into your browser for immediate display.

Surveyor Web Service Outputs

The survey results from the Surveyor web service will contain much more detail than the reports generated by the Surveyor interface, which provide only the most essential data. All web service outputs are in XML and conform to the Species Schema. See that document for a complete list of the data fields included, noting that the root element of all responses is mjdResponse. Note that all outputs contain a “schemaLocation” attribute in their root element, to enable validating XML parsers to automatically find and validate against the correct schema.

Output Formats

There are three possible output formats, depending on the size of the area of interest: Detailed, General, and Known, as shown below.

Area Type or Polygon Area

Output Format

County

Detailed

USGS 8-digit HUC

Detailed

USGS 7.5' Quad

Detailed

Polygon greater than or equal to 36 square km

Detailed

Polygon between 36 and 10 square km

General

Polygon between 10 and 2.6 square km (1 square mile)

Known

 

Sensitive Species

In order to allow as much detailed information as possible, without compromising the location of certain exceptionally sensitive species, element occurrences can be marked as “sensitive species.” Doing so removes them from detailed reporting in the response. Where this occurs, the <sensitiveSpeciesEncountered> element will be present, after any normal results.

Information is given as to the data steward(s) who may be contacted if further information is required, as in the following hypothetical example:

<sensitiveSpeciesEncountered>

<message>In addition to any results shown, your survey returned at least one result of a sensitive species occurrence which could not be shown. If you need more detailed information, please contact the data steward(s).

</message>

<dataStewards>

<dataSteward>Ohio Natural Heritage Database</dataSteward>

</dataStewards>

</sensitiveSpeciesEncountered>

“Fuzzed” Records

In some instances, your query results may include a flag telling you that the supplied spatial parameter has intersected element occurrence records whose spatial footprint has been intentionally made less precise. This is often because the species is subject to collection, deliberate vandalism, or inadvertent destruction and its locations are therefore considered especially sensitive.

In the Detailed output, the “fuzzed records” flag is placed on individual element occurrences. In the General output, if all element occurrences for a given species have been fuzzed, the web service output will contain a distinct flag on that species record. In the Known output, if all the element occurrence data in your output were fuzzed, the “Yes” response will also contain this flag.

Excluded Areas

In some cases, your query results may tell you that the supplied spatial parameter overlapped with a jurisdiction that did not allow the provision of any data or overlapped specifically excluded areas within a jurisdiction. The latter can include certain military and tribal lands where we are prohibited from releasing any data, or other large areas where we are complying with landowner privacy requests and requirements.

Data Gap

If an entire state or province has a significant non-spatial gap in the data they provide, a “data gap” flag will be placed on the output for queries that intersect that state or province. For example, although Washington State is not an excluded area (there are data provided from the state), we are not currently able to provide any data for animals from Washington State; so any query that intersects Washington State will receive a “data gap” flag stating that this is the case.

Details are shown at the state/province level and are of the form (for example):

<dataGaps>

<dataGap subnationCode="WA">No data for animals are available from the state of Washington.

</dataGap>

</dataGaps>

Errors

If the request contains errors, the service will respond with an HTTP error code of “400 (BAD_REQUEST)” and the body of the response will contain an XML list of errors in the format:

<errors>

<error>Error message 1</error>

<error>Error message 2</error>

<error>(etc)</error>

</errors>

 
Messages relate to:
  • Missing parameters
  • Invalid usernames/passwords
  • Invalid subscription
  • Invalidly specified area of interest (e.g., a FIPS county code that is not exactly 5 digits)
  • Unknown area of interest (e.g., a FIPS county code that does not refer to any known county)
  • Syntactically incorrect polygons
  • Polygons too small to be allowed in queries
  • Polygons that fall completely outside of the service coverage area

Internet Explorer (IE) users please note: IE has the facility to “Show friendly HTTP error messages” and this is the default setting. With friendly messages, IE will respond to an error from the service with a generic “Page Unavailable,” rather than the actual error messages. This may be “friendly,” but is uninformative and, in this case, misleading. To allow the correct display of error messages, the user should open IE and go toTools > Internet Options > Advanced and uncheck the “Show friendly HTTP error messages” option, then click OK.

There is a 4,000 character limit on the size of a “GET” request. If large polygons are to be submitted, it is advisable to use the “POST” method, which has no such restriction. For web pages, this would give a <form> tag with the “method” attribute set to POST.