...
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. |
| 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 |
The entire list of active layers in the COVAR_SPAT_CAUS table for decimal latitude = 44.0430722, decimal longitude = -123.0766368 in XML format | |
The PLAND Fragstat values for decimal latitude = 44.0430722, decimal longitude = -123.0766368 in XML format | |
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"?> | Header information includes the AKN COVAR_SPAT DTD |
Response to a mal-formed find request
Example Value | Description |
| |
---|---|---|---|
<?xml version="1.0" encoding="UTF-8"?> | Header information includes the AKN COVAR_SPAT 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 | 4 5 | Text terminated by a newline | RECORD COUNT=316536 |
Separator | Blank Line | 5 6 | newline |
|
Field Listing | Field Listing | 6 7 | Comma separated text terminated by a newline | FIELD NAME, DESCRIPTIVE NAME, SOURCE TABLE NAME, FIELD VALUE, FIELD VALUE DESCRIPTION, RADIUS, CLASS |
Field data | Field data | 7 8 to end of data | Comma separated text terminated by a newline | CAUS_PREC0101, 7, G 5.01 - 10.00, , |
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=format=csv&match=decLon=-123.0766368 |
| 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)Malformed request. Request must include a global unique identifier or lat/lon parameters. |
Separator | Blank Line | N + 1 | newline |
|