Page History

Frequency Histograms

API Parameters

...

Note

...

title

...

Period
- What portion of year?
- Which years?

Species
1. all present at location
2. short list
3. single species

Collections

For the EBIRD dataService, only the EBIRD data collection will be available initially (i.e., all the data used for unrestricted, normal eBird clones). When the eBird application begins to use this API to generate frequency histograms, we will need to expand the list of EBIRD collections to include DOD, CKWRI, GCBO. The reason for this is that these clones use datasets other than the standard unrestricted eBird dataset that most clones for their output.

parameter group	description	parameter name	implementation status	values	example value	default
location service	required	dataService	deployed	AKN, EBIRD (i.e. this tells which warehouse to utilize)	AKN	none
location	required	location	deployed	One of eBird standard subnational1 codes ,	exactly one location parameter is required	subnational1	eBird standard subnational1 codes	US-FL	n/a	country	2-letter ISO codes	CA	n/a	bcr	, integers 1- 64?	14	66, ebird subnat2 codes	US-FL	none n/a
		subnational2	required	locationType	deployed	One of subnational1,country,bcr,subnational2	subnational1	none eBird standard subnational2 codes
	n/a
period	period parameters are optionalDefines a specific period of interest if specified, both must be provided constraint beginYear <= endYear
	optional	beginYear	deployed	defines beginning year of period of interest , in YYYY format	2000	???? 1900
	optional	endYear	deployed	defines end year of period of interest , in YYYY format	2000	2008 (i.e., current year)
????
collection	defines dataset(s) of interest required	collection	deployed	AKN collection codes, eBird project IDs; initially there will be no away to request the entirety of AKN data as a collection valid collection codes for AKN dataService: All, ARCTICSURVEY, BBS, Banding, GBBC, HawkCount, KBMNPC, LACP, LBMP, MBW, MMP, PFW, PIF_CA_AREA, PIF_CA_PC, PRBO-PC, RMBO-SS, RMBO_PT, EBIRD, EBIRD_AK, EBIRD_BCN, EBIRD_CA, EBIRD_CAN, EBIRD_CBW, EBIRD_CUBA, EBIRD_GCBO, EBIRD_HISP, EBIRD_KLAM_SISK, EBIRD_LWBA, EBIRD_MA, EBIRD_MEX, EBIRD_NY, EBIRD_PR	n/a	, EBIRD_PRIMIG, EBIRD_TX, EBIRD_USVI, EBIRD_VT, EBIRD_WI valid collection codes for EBIRD dataservice: EBIRD multiple collection codes may be requested by including a collection=value parameter for every collection of interest	BBS	none

species	defines Specifies species of interest. optional	species either "all" or scientific name of single	deployed	Request species data using scientific name. data for multiple species may be requested by including a species=value parameter fro every species of interest	Sialia sialis	all

format	Specify response format. optional	format	deployed	"csv" = comma separated values "htfull" = Response is a hypertext document "htfrag" = Response is a hypertext <table> structure (usage: to be included inside an HTML wrapper) "jsfunc" = Response is a JavaScript function "jsdoc" = Response is JavaScript document.write() statement. Not yet implemented: "img" = returns image for single species; valid only when single species is requested Not yet implemented: "xml"	jsdoc	htfull

output	What to return as values in csv and xml formats. optional	output	deployed	output	defines form of output	output	"f" = returns frequency (float, 0.0-1.0) data A year's data is divided into 48 time periods, 4 time periods for each month. These periods are 7 days each for period one through three, with period four containing all remaining days of the month (i.e., 7 to 11 days) An empty field represents no data available for that time period A field containing a "P" indicates the bird was reported on a checklist, but the checklist was not reporting all species. A field containing a "0" indicates that checklists were submitted for that time period, but that the species was not reported. A field containing a numeric value greater than 0 and less than or equal to 1 indicates the frequency of positive sightings for that time period. Not yet implemented: "c" = returns category (integer, 1-5)	f	f

locale	defines language to use for common names optional	locale	not implemented	Java standard locale code	en_US	en_US

CSV Format Output (or tab delimited)

if S species are returned, the response has S+1 rows
- row #1 contains N for each of 48 "weeks"
- rows 2 through S+1 contain species name and frequency (0 <= frequency <= 1)
the response contains 50 columns

...


jsFunctionName	specifies the name of the javascript function to be returned	jsFunctionName	deployed	Used only when format=jsfunc. This parameter specifies the name of the function that is to be defined in the JavaScript file that is returned. Not required.	myFreqChart	AKNFreqHist

Example URLs

Deployed URL	Response
http://www.avianknowledge.net/ws1.0/product/freqhist?dataService=AKN&location=US-ME&locationType=subnational1&collection=all&format=csv	Raw data in CSV format for the state of Maine, all collections.
http://www.avianknowledge.net/ws1.0/product/freqhist?dataService=AKN&location=US-VT&locationType=subnational1&collection=MBW&format=htfull	Result data in fully formatted HTML for the state of Vermont, the Mountain Bird Watch collection.
http://www.avianknowledge.net/ws1.0/product/freqhist?dataService=AKN&location=US-PA&locationType=subnational1&collection=HawkCount&collection=EBIRD&format=jsdoc	Result data formatted for a JavaScript doc.write() call for the state of Pennsylvania, HawkCount and eBird collections.
http://www.avianknowledge.net/ws1.0/product/freqhist?dataService=AKN&location=US-CA&locationType=subnational1&collection=PRBO-PC&format=jsfunc&jsFunctionName=showAKNBarChart	Result data formatted for display by a Javascript function named showAKNBarChart. The data request is for the state of California, the PRBO Point Count collection.

Response to a well-formed Frequency Histogram Request

Note

title	Note

The number of header lines may need to be flexible to accommodate one line for each collection. Actual collection citations may need to be put into the header in this manner.

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 2008 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
Sample Size	Sample Size	6 through S (S - 1 = number of collections included in response, line S is the TOTAL sample size)	Comma delimited text, terminated by a newline. The first field contains the Collection Code, the second field contains the string "Sample Size," followed by 48 integer values.	EBIRD,Sample Size,64,44,58,96,57,64,100,65,78,133,113,145,111,119,122,152,83,95,120,161,94,73,72,129,117,58,69,105,57,51,53,77,64,68,78,77,51,83,88,162,94,60,71,76,55,43,99,123 BBS,Sample Size,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1693,3444,4223,5816,1294,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 MBW,Sample Size,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,96,186,182,30,0,3,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 TOTAL,Sample Size,64,44,58,96,57,64,100,65,78,133,113,145,111,119,122,152,83,95,120,161,1883,3703,4477,5975,1411,61,69,105,57,51,53,77,64,68,78,77,51,83,88,162,94,60,71,76,55,43,99,123
Separator	Blank Line	S + 1	newline
Frequency Data	Data	S + 2 through N - 1 (N = RECORD COUNT)	Comma delimited text, terminated by a newline A year's data is divided into 48 time periods, 4 time periods for each month. The time period data is preceeded by the common name and the scientific name. An empty field represents no data available for that time period A field containing a "P" indicates the bird was reported on a checklist, but the checklist was not reporting all species. A field containing a "0" indicates that checklists were submitted for that time period, but that the species was not reported. A field containing a numeric value greater than 0 and less than or equal to 1 indicates the frequency of positive sightings for that time period.	Common Goldeneye,Bucephala clangula,0.078125,0.02272,0.103448,0.083,0.122,0.078,0.079,0.061,0.089,0.11278,0.123,0.089,0.0360,0.0168,0.0327,0.0328,0,0.04210,0.0083,0,5.3106744E-4,5.4010E-4,6.7009E-4,3.346720E-4,7.0871E-4,0.01612,P,0,0,0.01960,P,0,0,0.014705,0,0,0,0,0.0113,0.0061,0.0106,0.016,0.028,0.039,0.090,0.09,0.24,0.19

Response to a well-formed Frequency Histogram Request (Zero Record Response)

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 2008 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=0
Separator	Blank Line	5	newline

Response to a mal-formed Frequency Histogram 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=dataService=AKN&location=US-ME&locationType=subnational1
	Errors	3 - N	Text terminated by a newline	The collection parameter is required (i.e. collection=MBW).
Separator	Blank Line	N + 1	newline

Example JavaScript Response

jsfunc Format

No Format


function AKNFreqHist () {

return '<link rel="stylesheet" type="text/css" href="http://akn.ornith.cornell.edu/styles/histogram.css"                  /><table class="obs-histogram"><thead><tr><td class="sp" title=""></td><td>Jan</td><td>Feb</td><td>Mar</td><td>Apr</td><td>May</td><td>Jun</td><td>Jul</td><td>Aug</td><td>Sep</td><td>Oct</td><td>Nov</td><td>Dec</td></tr></thead><tbody></tr><tr id="sp305" class="o""><td class="sp" title="Passer domesticus">House Sparrow</td><td><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /><img src="http://akn.ornith.cornell.edu/images/03.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/05.gif"                  /><img src="http://akn.ornith.cornell.edu/images/05.gif"                  /><img src="http://akn.ornith.cornell.edu/images/05.gif"                  /><img src="http://akn.ornith.cornell.edu/images/05.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/09.gif"                  /><img src="http://akn.ornith.cornell.edu/images/05.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/sp.gif"                  /><img src="http://akn.ornith.cornell.edu/images/sp.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /></td><td><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /><img src="http://akn.ornith.cornell.edu/images/no.gif"                  /></td></tr></tbody></table>';
}

jsdoc Format