FreeDemographics.com API

API Documentation

In as little as a five minutes, complete demographic data and reports can be streamed directly to your web site - no infrastructure, no overhead, no hassles.

Contents

Overview
Basic Reporting
Classes

AllocateGeocoder
ACandidate
AllocateEngine
AChart
AReport
AGeography
ARing
AZipcode
AState
ACounty

Style

API Documentation

Overview

The FreeDemographics.com service is delivered as a simple Javascript API designed to be simply included in web pages of your own design with the <script> HTML tag. Once included in in the source of a web page, it is possible to use the FreeDemographics.com API to stream demographic data and reports directly to your web site.

Basic Reporting

Including the FreeDemographics.com API on a web page is simply a matter of including the following <script> tag in your web page.

										<script 
											src="http://belay.extendthereach.com/api/engine/api.aspx?key=
											D9D79DB1A3D203AA8964650DE1D34978C9E518E6CC099F34" 
											type="text/javascript"></script>
									

Once the FreeDemographics.com API has been added in an HTML <script> tag, adding demographic reports or charts is simply a matter of creating a registering an AllocateEngine object and adding either AReport or AChart objects.

										<html>

											<head>

											<title>Sample Report</title>

											<link href="http://belay.extendthereach.com/api/css/AReportControl.css" 
											type="text/css" rel="stylesheet">

											<script src="http://belay.extendthereach.com/api/engine/api.aspx?key=
											D9D79DB1A3D203AA8964650DE1D34978C9E518E6CC099F34" 
											type="text/javascript"></script>

											<script type="text/javascript" language="Javascript">

											//<![CDATA[

											var demo = null;

											function initPage() {

											demo = new AllocateEngine(document.getElementById("demoControl"));

											var geos = [];

											geos.push(new AZipcode('70115'));

											geos.push(new AZipcode('90210'));

											var chart = new AChart(geos, AChart.FD_POPULATION_COMPARISON_CHART);

											demo.addChart(chart);

											var report = new AReport(geos, AReport.FD_80_TO_00_COMPARISON_REPORT);

											demo.addReport(report);

											}

											//]]>

											</script>

											</head>

											<body onload="initPage();">

											</body>

											<div id="demoControl" style="width:500px; height:500px;" />

											</html>

Classes

There are four main groups of objects exposed as part of the FreeDemographics.com API: The AllocateEngine, AllocateGeocoder, reports and charts, and finally geographies.

AllocateGeocoder
The AllocateGeocoder object is responsible for geocoding addresses (or postal codes) and returning an array of ACandidate objects.

										
												Constructor
											
												AllocateGeocoder(obj)
												Initializes 
													and creates a new AGeocoder control.
											
												Members
											
												void
													geocodeAddress(string street,

													    string city,

													    string state,

													    string postalCode,

													    function callback(ACandidate[]))
												Geocodes an address (or postal code) and calls the specified callback
													function when complete.

										var geocoder = new AllocateGeocoder();

										geocoder.geocodeAddress(

										    '1600 Pennsylvania Ave',

										    'Washington',

										    'DC',

										    '',

										    function(candidates) {

										        var s = '';

										        for (var i = 0; i < candidates.length; i++) {

										            s += candidates[i].getFirstLine() + '\n';

										            s += candidates[i].getLastLine() + '\n';

										            s += '(' + candidates[i].getPoint().getLongitude();

										            s += ', ' + candidates[i].getPoint().getLatitude() + ')\n\n';

										        }

										        alert(s);

										    }

										);

ACandidate
The ACandidate object defines a potential match from a geocode operation.

										
												Members
											
												string
													getFirstLine()
												Returns the 
													first line of an address candidate match.
											
												string
													getLastLine()
												Returns the 
													last line of an address candidate match.
											
												APoint
													getPoint()
												Returns an APoint object indicating
													location of the candidate match.

AllocateEngine
The AllocateEngine object is primarily responsible for rendering and processing report and charts requests. The AllocateEngine object is initialized with a reference to a <div> HTML tag.

										
												Constructor
											
												AllocateEngine(obj)
												Initializes 
													and creates a new FreeDemographics.com control. The obj should be an HTML <div>
													tag.
											
												Members
											
												void
													addChart(AChart chart)
												Adds a chart 
													to the FreeDemographics.com control.
											
												void
													addReport(AReport report)
												Adds a 
													pre-defined demographic report to the FreeDemographics.com control.
											
												void
													clearAllReports()
												Removes all 
													reports and charts from the control.

AChart
The AChart object defines the geographies and pre-definined chart to display. The AChart object is limited to displaying information for 4 or fewer geographies.

										
												Constructor
											
												AChart(AGeography[]
													geos,

													    int chartNumber)
												Initializes 
													and creates a new AChart object with the supplied chart number and AGeography 
													array.
											
												Members
											
												int
													geographyCount()
												Returns the 
													total number of geographies in the chart.
											
												AGeography[]
													getGeographies()
												Returns an 
													array of AGeography objects contained in the chart.
											
												Static Members
											
												int
													FD_POPULATION_COMPARISON_CHART
												1980 to 2000 Population Comparison Chart
											
												int
													FD_CENSUS_2000_INCOME_CHART
												Census 2000 Income Chart
											
												int
													FD_CENSUS_2000_HOUSING_CHART
												Census 2000 Housing Chart
											
												int
													FD_CENSUS_2000_RACE_ETHNICITY_CHART
												Census 2000 Race & Ethnicity Chart

AReport
The AReport object defines the geographies and pre-definined report to display. The AReport object is limited to displaying a report with information for 4 or fewer geographies.

										
												Constructor
											
												AReport(AGeography[]
													geos,

													    int reportNumber)
												Initializes 
													and creates a new AReport object with the supplied report number and AGeography 
													array.
											
												Members
											
												int
													geographyCount()
												Returns the 
													total number of geographies in the report.
											
												AGeography[]
													getGeographies()
												Returns an 
													array of AGeography objects contained in the report.
											
												Static Members
											
												int
													FD_80_TO_00_COMPARISON_REPORT
												1980 to 2000 Comparison Report
											
												int
													FD_CENSUS_2000_COMPARISON_REPORT
												Census 2000 Basic Comparison Report
											
												int
													FD_CENSUS_2000_INCOME_HOUSING_REPORT
												Census 2000 Income & Housing Report
											
												int
													FD_CENSUS_2000_INCOME_REPORT
												Census 2000 Basic Income Report
											
												int
													FD_CENSUS_2000_OCCUPATION_REPORT
												Census 2000 Occupation & Employment Report
											
												int
													FD_CENSUS_2000_RACE_ANCESTRY_REPORT
												Census 2000 Race & Ancestry Report
											
												int
													FD_CENSUS_2000_AGE_REPORT
												Census 2000 Age Report

AGeography
The AGeography is the root interface for all geography objects: ARing, AZipcode, AState and ACounty.

										
												Members
											
												string
													getLabel()
												Returns the 
													label of the object.
											
												void
													setLabel(label)
												Sets the label 
													of the object.
											
												string
													getClassName()
												Returns class 
													name of the object. Valid strings include 'ARing', 'AZipcode', 'AState' 
													and 'ACounty'.

APoint : AGeography
The APoint object defines an AGeography object that represents a simple simple point object in geographic coordinates.

										
												Constructor
											
												APoint(float
													lon,

													    float lat)
												Initializes 
													and creates a new APoint object with the specified center point (in 
													longitude/latitude coordinates).
											
												Members
											
												float
													getLongitude()
												Returns the X 
													coordinate (or longitude) of the point object.
											
												float
													getLatitude()
												Returns the Y 
													coordinate (or latitude) of the point object.
											
												void
													setLongitude()
												Sets the 
													X coordinate (or longitude) of the point object.
											
												void
													setLatitude()
												Sets the 
													Y coordinate (or latitude) of the point object.
											
												void
													set(float lon,

													    float lat)
												Sets the 
													X and Y coordinates of the point object.

ARing : AGeography
The ARing object defines an AGeography object that represents a simple radius around a central locaiton. The ARing object is defined by the center of the ring (expressed in Longitude/Latitude coordinates), and the radius of the ring. The maximum radius for any ARing object is 10 miles.

										
												Constructor
											
												ARing(APoint
													pt,

													    float radius,

													    [string label])
												Initializes 
													and creates a new ARing object with the specified center point (in 
													longitude/latitude coordinates), radius (in miles) from the cetnter point, and 
													optional label.
											
												Members
											
												float
													getCenterX()
												Returns the X 
													coordinate (or longitude) of the center of the ring object.
											
												float
													getCenterY()
												Returns the Y 
													coordinate (or latitude) of the center of the ring object.
											
												float
													getRadius()
												Returns radius 
													of the ring object. Distance is set (and returned) in miles from the ring 
													center point.

AZipcode : AGeography
The AZipcode object defines an AGeography object that represents a USPS postal code boundary.

										
												Constructor
											
												AZipcode(string
													zipcode)
												Initializes 
													and creates a new AZipcode object. USPS postal codes are always identified by a 
													sequence of 5 digits (i.e. '90210', or '02206').
											
												Members
											
												string
													getZipcode()
												Returns the 
													USPS postal code for this AZipcode object.

AState : AGeography
The AState object defines an AGeography object that represents a State in the United States of America.

										
												Constructor
											
												AState(string
													st)
												Initializes 
													and creates a new AState object. The constructor requires a single USPS postal 
													code abbreviation for a State in the United States of America (i.e. 'AK', 'CA', 
													'GA' or 'MT').
											
												Members
											
												string
													getState()
												Returns the 
													2-character USPS postal code abbreviation for this AState object.

ACounty : AGeography
The ACounty object defines an AGeography object that represents a County (Parish or Borough) in a State.

										
												Constructor
											
												ACounty(string
													fips)
												Initializes 
													and creates a new ACounty object. The constructor requires a single 5-character 
														FIPS code for a county in the United States of America (i.e. '08013', 
													'06037' or '17031').
											
												Members
											
												string
													getCounty()
												Returns the 
													5-character fips code abbreviation for this ACounty object.

Style

The FreeDemogaphics.com API allows for complete adjustment of the style and format of the control. This level of control is achieved through the use of Cascading Style Sheets (CSS).

table.all_table
Specifies the style for the FreeDemographics.com API control. All demographic content is contained within this master table. Specifying a style here will affect the entire control.

td.all_td_header_label
Specifies the style for the geography labels for a AReport. This is the row above the demogaphic content and below the report title.

td.all_td_row_label_even
Specifies the style for the demographic variable labels for a AReport. This style will only affect even rows. This feature allows for row styles in an alternating fashion. This style only affects the variable label cell.

td.all_td_row_label_odd
Specifies the style for the demographic variable labels for a AReport. This style will only affect odd rows. This feature allows for row styles in an alternating fashion. This style only affects the variable label cell.

td.all_td_value
Specifies the style for the demographic variable values in an AReport.

tr.all_tr_menuTitle
Specifies the style for the pull-down menu title bar for the FreeDemographics.com control. This row is only visible if the user elects to activate the pull-down menu by clicking on the menu icon in the upper-left corner of the control.

tr.all_tr_menu
Specifies the style for the pull-down menu (i.e. the background) for the FreeDemographics.com control. This row is only visible if the user elects to activate the pull-down menu by clicking on the menu icon in the upper-left corner of the control.

td.all_td_menu
Specifies the style for the pull-down menu (i.e. the menu cell) for the FreeDemographics.com control. This cell is only visible if the user elects to activate the pull-down menu by clicking on the menu icon in the upper-left corner of the control.

td.all_td_menu
Specifies the link style for the pull-down menu options. These links are only visible if the user elects to activate the pull-down menu by clicking on the menu icon in the upper-left corner of the control.

span.all_menu_category
Specifies the font style for the pull-down menu categories. Currently, 'Reports' is the only menu category and will be the only one affected.

tr.all_tr_title
Specifies the style for the AReport or AChart title.

tr.all_tr_header
Specifies the style for the AReport geography header. This is the row below the AReport title and above the demographic content.

tr.all_tr_even
Specifies the style for all even rows in an AReport. This style will only affect even rows. This feature allows for row styles in an alternating fashion when used in conjunction with the tr.all_tr_odd style. This style affects the entire row of demographic content.

tr.all_tr_odd
Specifies the style for all odd rows in an AReport. This style will only affect odd rows. This feature allows for row styles in an alternating fashion when used in conjuction with the tr.all_tr_even style. This style affects the entire row of demographic content.