ESA XQuery Service

This page details how to access U.S. Fish & Wildlife Service Threatened & Endangered Species data remotely. The data available here was collected through the U.S. FWS ECOS project.

Data Access

The data provided is openly available to the public.

How to

The T&E XML schema is available at this URL:

http://ecos.fws.gov/ecp0/TessQuery?request=schema

XQueries may be executed against this schema at the following URL:

http://ecos.fws.gov/ecp0/TessQuery?request=query&xquery=[ XQuery ]

Note the two request parameters that must be set in order for the XQuery to be executed:

Parameter Value
request query
xquery a valid XQuery

If successful, a query request will return an xml document with the valid results of the query nested within a root <results> element. If an error occurs during query processing, an error message will be returned nested within a root <error> element.

Data definitions

The table below summarizes some of the data codes in the TESS Query response that are non-obvious:

<COUNTRY>
Value Definition
1 Domestic
2 Foreign
3 Both domestic and Foreign
<LEAD_AGENCY>
Value Definition
1 FWS
2 NMFS/NOAA
3 Joint FWS and NMFS/NOAA

Examples

Question Find all T&E species in the Cervidae family.
XQuery /SPECIES_DETAIL[FAMILY="Cervidae"]
URL http://ecos.fws.gov/ecp0/TessQuery?request=query&xquery=/SPECIES_DETAIL[FAMILY=%22Cervidae%22]
Results

Question List all distinct statuses of T&E species.
XQuery
                for $x in fn:distinct-values(/SPECIES_DETAIL/STATUS_TEXT)
                order by $x
                return
                <status>{$x}</status>
            
URL http://ecos.fws.gov/ecp0/TessQuery?request=query&xquery=for%20$x%20in%20fn:distinct-values(/SPECIES_DETAIL/STATUS_TEXT)%20order%20by%20$x%20return%20%3Cstatus%3E{$x}%3C/status%3E
Results

Question List the scientific and common name of all species which are of status "Threatened" or "Endangered".
XQuery
                for $item in /SPECIES_DETAIL
                where
                $item/STATUS eq "E" or
                $item/STATUS eq "T"
                return
                <SPECIES>{$item/ENTITY_ID,$item/SCINAME,$item/COMNAME,$item/STATUS,$item/STATUS_TEXT}</SPECIES>
            
URL http://ecos.fws.gov/ecp0/TessQuery?xquery=+for+%24item+in+%2FSPECIES_DETAIL%0D%0Awhere+%0D%0A%24item%2FSTATUS+eq+%22E%22+or%0D%0A%24item%2FSTATUS+eq+%22T%22+++%0D%0Areturn+%0D%0A%3CSPECIES%3E%7B%24item%2FENTITY_ID%2C%24item%2FSCINAME%2C%24item%2FCOMNAME%2C%24item%2FSTATUS%2C%24item%2FSTATUS_TEXT%7D%3C%2FSPECIES%3E&request=query
Results

Question Demonstration of error handling.
XQuery /BOGUS_ELEMENT
URL http://ecos.fws.gov/ecp0/TessQuery?request=query&xquery=/BOGUS_ELEMENT
Results

XQuery Entry

Type your own XQuery into the box below. After clicking "Run Query", the results will be displayed in another window.


Implementation Limitations

The XQuery implementation used by the service is a customized version of the XQuark 1.2 release of XQuark. The XQuark XQuery implementation does not implement the full XQuery 1.0 specification. More information may be found here.

References

XQuery Specification - World Wide Web Consortium

W3C Schools XQuery tutorial

XQuark