The service and discovery URLs provide basic information describing and listing the COVAR_SPAT data layer values that are available via the AKN web service. A layer list request returns the entire list of COVAR_SPAT and COVAR_FRAGSTAT attribute names. A metadata request returns a descriptive record for the requested attribute. Both the layer listing request and the metadata request will accept a format parameter that specifies a response data format of XML or CSV.

API Parameters

Layer List Request

URL

Description

Status

Notes

/ws1.0/ref/covar/list

Returns the entire list of COVAR_SPAT and COVAR_FRAGSTAT layers

Deployed

 

Parameter

Required

Default

Values

Example

Description

format

no

csv

"xml" or "csv"

format=xml

Format specification for data response

Metadata Request

URL

Description

Status

Notes

/ws1.0/ref/covar/metadata?match=<layer_name>

Metadata request for a specific COVAR layer

Deployed

 

Parameter

Required

Default

Values

Example

Description

match

yes

 

Any valid COVAR_SPAT or COVAR_FRAGSTAT layer name

match=caus_prec0101

Layer parameter for metadata request

format

no

csv

"xml" or "csv"

format=xml

Format specification for metadata request

Example URLs

Deployed URLs

Expected Response

http://ebird.org/ws1.0/ref/covar/list

The entire list of active COVAR layers in CSV format

http://ebird.org/ws1.0/ref/covar/list?format=xml

The entire list of active COVAR layers in XML format

http://ebird.org/ws1.0/ref/covar/metadata?match=caus_prec0101&format=csv

The metadata for the CAUS_PREC0101 layer in CSV format

http://ebird.org/ws1.0/ref/covar/metadata?match=caus_prec0101&format=xml

The metadata for the CAUS_PREC0101 layer in XML format

XML Result Formats

Response to a well-formed listing 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>Listing of COVAR_SPAT field names and source data tables</comment>
</header>
<result>
<covar-spat>
<covar-spat-metadata>
<data-record>
<attribute-data>
<field-name>AI</field-name>
<descriptive-name>Aggregation Index (Fragstats)</descriptive-name>
<source-table-name>COVAR_FS_CLASS_NLCD2001</source-table-name>
</attribute-data>
</data-record>
<data-record>
<attribute-data>
<field-name>AREA_AM</field-name>
<descriptive-name>Area-weighted mean patch area (Fragstats)</descriptive-name>
<source-table-name>COVAR_FS_CLASS_NLCD2001</source-table-name>
</attribute-data>
</data-record>
...
</covar-spat-metadata>
</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 data listing is a series of <data-record> elements. Each <data-record> contains 1 <attribute-data> element containing the <field-name>, a <descriptive-name>, and the <source-table-name> elements.


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

Response to a well-formed metadata 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:48:23.346-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 metadata response</comment>
</header>
<result>
<covar-spat>
<covar-spat-metadata>
<data-record>
<attribute-data>
<field-name>PLAND</field-name>
<descriptive-name>Percentage of landscape (Fragstats)</descriptive-name>
<description>PLAND = the sum of the areas of all patches of the corresponding patch type, divided by total landscape area, multiplied by 100</description>
<data-type>NUMBER</data-type>
<units>Number</units>
<min-value>Not Described</min-value>
<max-value>Not Described</max-value>
<min-value-description>Not Described</min-value-description>
<max-value-description>Not Described</max-value-description>
<nodata-value>-9999</nodata-value>
</attribute-data>
</data-record>
</covar-spat-metadata>
</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 data listing is a single <data-record> element. <data-record> contains 1 <attribute-data> element containing the <field-name>, <descriptive-name>, <description>, <data-type>, <units>, <min-value>, <max-value>, <min-value-description>, <max-value-description>, and the <nodata-value> elements.

This particular example is for a Fragstats attribute. There are no set maximum or minimum values for this statistic so the values are set to "Not Described." The "Not Described" value should be treated as NULL.

Some COVAR_SPAT values represent a value range. Many of the climate layers such as precipitation and temperature will have both <min-value>, <max-value>, and <min-value-description> and <max-value-description> data elements. In these cases where the data for a particular point is a data range the <min-value>, and <max-value> are discrete numeric values and the <min-value-description> and <max-value-description> describe the actual value range for the attribute.


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

Response to a mal-formed metadata 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:48:23.346-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>A well-formed metadata request includes a match=layer_name query parameter (i.e. match=CAUS_PREC0101).</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 the match parameter was 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 listing 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

 

Number of records returned

4

Text terminated by a newline

RECORD COUNT=316

Separator

Blank Line

5

newline

 

Field Listing

Field Listing

6

Comma separated text terminated by a newline

FIELD NAME, DESCRIPTIVE NAME, SOURCE TABLE NAME

Field data

Field data

7 to end of data

Comma separated text terminated by a newline

AI, Aggregation Index (Fragstats), COVAR_FS_CLASS_NLCD2001
AREA_AM, Area-weighted mean patch area (Fragstats), COVAR_FS_CLASS_NLCD2001
...

Response to a well-formed metadata 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

 

Number of records returned

4

Text terminated by a newline

RECORD COUNT=1

Separator

Blank Line

5

newline

 

Field Listing

Field Listing

6

Comma separated text terminated by a newline

FIELD NAME, DESCRIPTIVE NAME, DESCRIPTION, DATA TYPE, UNITS, MIN VALUE, MAX VALUE, MIN VALUE DESCRIPTION, MAX VALUE DESCRIPTION, NODATA VALUE

Field data

Field data

7

Comma separated text terminated by a newline

PLAND, Percentage of landscape (Fragstats), PLAND = the sum of the areas of all patches of the corresponding patch type divided by total landscape area multiplied by 100, NUMBER, Number, Not Described, Not Described, Not Described, Not Described, -9999

Response to a mal-formed metadata 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=format=csv&match=

 

Errors

3 - N

Text terminated by a newline

A well-formed metadata request includes a match=layer_name query parameter (i.e. match=CAUS_PREC0101).

Separator

Blank Line

N + 1

newline