The data retrieval URL, a find request, provides access to COVAR_SPAT and COVAR_FRAGSTAT layer data via latitude/longitude parameters, or a global unique identifier parameter for a single observation record. The find request will accept parameters to query for a single COVAR layer value, all layers in a specific COVAR table, or all layer values in the COVAR schema for a particular lat/lon or GlobalUniqueID. A find request will also accept a format parameter that specifies a response data format of XML or CSV.

Note: Currently, use of the GlobalUniqueID parameter is restricted to public data records only.

API Parameters

Find Request

URL

Description

Status

Notes

/ws1.0/data/covar/find?decLon=<lon>&decLat=<lat>&format=xml

Returns all COVAR_SPAT and COVAR_FRAGSTAT layer values for lat/lon in XML format

Deployed

 

/ws1.0/data/covar/find?guid=<guidValue>

Returns all COVAR_SPAT and COVAR_FRAGSTAT layer values for guidValue in CSV format

Deployed

Currently only available for public AKN records

/ws1.0/data/covar/find?guid=<guidValue>&table=<tableName>

Returns all layer values in the tableName table for guidValue in CSV format

Deployed

 

/ws1.0/data/covar/find?decLon=<lon>&decLat=<lat>&format=xml&table=<tableName>&layer=<layerName>

Returns the layerName value in the tableName table for lat/lon in XML format

Deployed

 

Parameter

Required

Default

Values

Example

Description

decLat & decLon

Required unless guid parameter is passed.

 

Any valid AKN decimal latitude and decimal longitude value

decLon=-123.0766368&decLat=44.0430722

 

guid

Required unless decLat & decLon parameters are passed.

 

Any valid AKN Global Unique Identifier

guid=URN:catalog:HMANA:HawkCount:1476880

 

table

Required if layer parameter is passed.
Required if data values for an entire table are desired.

 

Any valid AKN COVAR table name

table=covar_spat_caus

 

layer

no

 

Any valid AKN COVAR layer name

layer=caus_prec0101

 

format

no

csv

"xml" or "csv"

format=xml

Format specification for data response

Example URLs

Deployed URLs

Expected Response

http://ebird.org/ws1.0/data/covar/find?decLon=-123.0766368&decLat=44.0430722&format=xml

The entire list of active COVAR layers in XML format for decimal latitude = 44.0430722, decimal longitude = -123.0766368 in XML format

http://ebird.org/ws1.0/data/covar/find?decLon=-123.0766368&decLat=44.0430722&format=xml&table=covar_spat_caus

The entire list of active layers in the COVAR_SPAT_CAUS table for decimal latitude = 44.0430722, decimal longitude = -123.0766368 in XML format

http://ebird.org/ws1.0/data/covar/find?table=covar_fs_class_nlcd2001&layer=pland&decLon=-123.0766368&decLat=44.0430722&format=xml

The PLAND Fragstat values for decimal latitude = 44.0430722, decimal longitude = -123.0766368 in XML format

http://ebird.org/ws1.0/data/covar/find?table=covar_fs_landscape_nlcd2001&guid=URN:catalog:HMANA:HawkCount:1476880

All of the values in the COVAR_FS_LANDSCAPE_NLCD2001 table for the GlobalUniqueID = URN:catalog:HMANA:HawkCount:1476880 in CSV format

XML Result Formats

Responses to a well-formed find request

Example Value

Description

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE response PUBLIC "-//Avian Knowledge Network//DTD COVAR_SPAT 1.0//EN" "http://akn.ornith.cornell.edu/dtd/covar_spat_1_0.dtd">
<response>
<header>
<locale country="US" language="en"/>
<timestamp>2009-05-06T07:31:23.017-04:00</timestamp>
<criteria/>
<copyright>Copyright 2009 Cornell Lab of Ornithology - http://www.birds.cornell.edu</copyright>
<data-policy>AKN Data Sharing Policy - http://www.avianknowledge.net/content/about/akn-data-sharing-policy</data-policy>
<comment>COVAR_SPAT data response for PLAND</comment>
</header>
<result>
<covar-spat global-unique-ident="URN:catalog:HMANA:HawkCount:1476880" decimal-latitude="42.0666667" decimal-longitude="-83.1936944">
<covar-fragstat-class>
<data-record>
<attribute-data>
<field-name>RADIUS</field-name>
<field-value>75</field-value>
</attribute-data>
<attribute-data>
<field-name>CLASS</field-name>
<field-value>21</field-value>
</attribute-data>
<attribute-data>
<field-name>PLAND</field-name>
<field-value>84</field-value>
</attribute-data>
</data-record>
<data-record>
<attribute-data>
<field-name>RADIUS</field-name>
<field-value>75</field-value>
</attribute-data>
<attribute-data>
<field-name>CLASS</field-name>
<field-value>23</field-value>
</attribute-data>
<attribute-data>
<field-name>PLAND</field-name>
<field-value>16</field-value>
</attribute-data>
</data-record>
...
</covar-fragstat-class>
</covar-spat>
</result
</response>

Header information includes the AKN COVAR_SPAT DTD
The timestamp of the response
A copyright element
The AKN data sharing policy element
A comment element

The <covar-spat> element will contain decimal_latitude and decimal_longitude attributes from the request parameters, as well as a global-unique-ident attribute if the data request was based on a GlobalUniqueID.

The data listing is a series of <tableName> elements containing <data-record> elements. (Each <tableName> element identifies the name of the particular source table from which the data was pulled.) The <data-record> element contains 1 <attribute-data> element if the request was for a specific layer value, and N <attribute-data> elements if the request was for the contents of the entire table. The <attribute-data> contains the <field-name>, and <field-value> elements. If the <field-value> is a data range, i.e. precipitation and some temperature attributes are expressed as a range, the <attribute-data> will include a <field-value-description> element containing the actual data range string for the value (See the discussion about data range in the /ws1.0/ref/covar/metadata request.)


Reference DTD for XML schema details http://akn.ornith.cornell.edu/dtd/covar_spat_1_0.dtd

Response to a mal-formed find request

Example Value

Description

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE response PUBLIC "-//Avian Knowledge Network//DTD COVAR_SPAT 1.0//EN" "http://akn.ornith.cornell.edu/dtd/covar_spat_1_0.dtd">
<response>
<header>
<locale country="US" language="en"/>
<timestamp>2009-05-08T07:38:51.347-04:00</timestamp>
<criteria/>
<copyright>Copyright 2009 Cornell Lab of Ornithology - http://www.birds.cornell.edu</copyright>
<data-policy>AKN Data Sharing Policy - http://www.avianknowledge.net/content/about/akn-data-sharing-policy</data-policy>
<comment>Malformed Request. Request must include a global unique identifier or lat/lon parameters.</comment>
</header>
<result/>
</response>

Header information includes the AKN COVAR_SPAT DTD
The timestamp of the response
A copyright element
The AKN data sharing policy element
A comment element

The comment states that required parameters were missing or empty.


Reference DTD for XML schema details http://akn.ornith.cornell.edu/dtd/covar_spat_1_0.dtd

CSV Result Formats

Response to a well-formed find request

Description

Name

Line Number

Format

Example Value

Status

Status

1

Text terminated by a newline

DATA

Header

Copyright

2

Text terminated by a newline

Copyright 2009 Cornell Lab of Ornithology  http://www.birds.cornell.edu

 

Data Policy

3

Text terminated by a newline

AKN Data Sharing Policy http://www.avianknowledge.net/content/about/akn-data-sharing-policy

 

Request Parameters

4

Text terminated by a newline

REQUEST PARAMETERS=decLon=-123.0766368&decLat=44.0430722&format=csv

 

Number of records returned

5

Text terminated by a newline

RECORD COUNT=536

Separator

Blank Line

6

newline

 

Field Listing

Field Listing

7

Comma separated text terminated by a newline

FIELD NAME, FIELD VALUE, FIELD VALUE DESCRIPTION, RADIUS, CLASS

Field data

Field data

8 to end of data

Comma separated text terminated by a newline

CAUS_PREC0101, 7, G 5.01 - 10.00, ,
CAUS_PREC0102, 6, F 3.01 - 5.00, ,
CAUS_PREC0103, 6, F 3.01 - 5.00, ,
...
PLAND, 68, , 75, 22
PD, 44.4444, , 75, 22
ED, 160, , 75, 22
...

Response to a mal-formed find request

Description

Name

Line Number

Format

Example Value

Status

Status

1

Text terminated by a newline

ERROR

Header

Request Parameters

2

Text terminated by a newline

REQUEST PARAMETERS=decLon=-123.0766368

 

Errors

3 - N

Text terminated by a newline

Malformed request. Request must include a global unique identifier or lat/lon parameters.

Separator

Blank Line

N + 1

newline

 
  • No labels