In addition to the numeric result values, many of our statistics have corresponding trend (up, down, mixed, na) and trend strength (strong, weak, na). These can be retrieved by the same API by using the name of the trend or trend strength statistic. The recent price trend:

http://stats.altosresearch.com/altos/app?pai=100&s=median_price_trend&ra=a&q=a&st=CA&c=SUNNYVALE&z=94086&service=statXml

The XML returned now carries the trend text ‘DOWN’ in the body of the <stat> element:

The strength of a trend is obtained using the ‘_trend_strength’ stat:

http://stats.altosresearch.com/altos/app?pai=100&s=median_price_trend_strength&ra=a&q=a&st=CA&c=SUNNYVALE&z=94086&service=statXml

With the resulting XML:

<stat name="median_price_trend_strength" state="CA" city="SUNNYVALE" zip="94086" resType="single_family" rollingAverage="SEVEN_DAY" quartile="ALL" date="2011-07-22">STRONG</stat>

Regional Stat Examples

The median price for the Chicago Area MSA, single family homes:

http://stats.altosresearch.com/altos/app?pai=100&s=price&rt=sf&ra=a&q=a&z=chicago-naperville-joliet&service=zrxml

General API Guidelines

The Altos Research chart and data APIs are based on a simple HTTP/REST request format. All of the options are included as name=value pairs in the URL. The base URL for all chart requests is:

http://charts.altosresearch.com/altos/app

For all stats data APIs, the base URL is:

http://stats.altosresearch.com/altos/app

In addition, we require that all requests include a partner ID value. This is assigned to you when you create an account with Altos Research. The partner ID must be included in all requests to chart and data APIs:

http://charts.altosresearch.com/altos/app?pai=123456

http://stats.altosresearch.com/altos/app?pai=123456

All URL parameters are appended to the URL - the order is not important - separated by the ampersand character - ‘&’ - as in:

http://charts.altosresearch.com/altos/app?pai=123456&service=chart&st=CA

Specifying the Service

Through our APIs, we offer access to multiple services. These are specified in the URL using the ‘service=’ parameter. Our service indicators are:

chart (‘service=chart’): State/city/zip-level charts
zrchart (‘service=zrchart’): Regional charts
statXml (‘service=statXml’): State/city/zip-level statistics, returned in XML format
zrxml (‘service=zrxml’): Regional statistics, returned in XML format

Examples:

http://charts.altosresearch.com/altos/app?pai=123456&service=chart

http://charts.altosresearch.com/altos/app?pai=123456&service=zrchart

http://charts.altosresearch.com/altos/app?pai=123456&service=statXml

http://charts.altosresearch.com/altos/app?pai=123456&service=zrxml

Specifying the Location

Our APIs allow you to retrieve charts and data aggregated at two levels:

state/city/zip: The most granular level of data we provide is at the zip code. To access this data via our APIs you’ll need to specify the state, city name and zip code in the request.
regional: We also offer data that has been aggregated at the regional level. We use the term ‘region’ to refer to a set of zip codes. Regions are used to define counties (all of the zip codes in Santa Clara County, CA), market areas (all of the zip codes in the San Francisco Bay Area) and even our national indices.

For state/city/zip locations, we use a combination of three URL parameters: ‘st’, ‘c’ and ‘z’. You must include all three to completely specify a location:

st=CA&c=SUNNYVALE&z=94086

For city names that contain space characters, remember to URL encode the space with either a ‘+’ or ‘%20’:

st=CA&c=SAN+JOSE&z=95124

If instead of a specific zip code, you can also specify the special zip code value ‘a’ to indicate the average of all zip codes for a city.

st=CA&c=SAN+FRANCISCO&z=a

For the chart APIs, you can specify multiple locations by comma-separated values. To select Sunnyvale, CA 94086 and Chicago, IL 60610, you would specify:

st=CA,IL&c=SUNNYVALE,CHICAGO&z=94086,60610

For regional level data, the name of the region is specified using the ‘z=’ parameter:

z=altos-20-composite

You can also specify multiple regions by comma separating the region names:

z=altos-20-composite,san-diego-carlsbad-san-marcos-msa

Specifying the Statistic

Altos tracks over 80 different measures (Price, Inventory, Days on Market, Price per Square Foot) for every location we cover. These measures are then divided into multiple statistics - median, mean, min, max, peak and trough, resulting in nearly 500 different statistical values. In all of our APIs, the statistic is specified using the ‘s=’ URL parameter:

s=median_price

In charting applications, multiple statistics can be specified in a comma-separated list:

s=median_price,median_inventory

When including multiple statistics in a chart, you may need to plot the two stats along different Y-axes (price and inventory are commonly handled this way). You can specify either the left or right axis on a per-statistic basis using ‘:r’ or ‘:l’ after the stat name:

s=median_price:r,median_inventory:l

Unfortunately, the set of statistic names differs depending on whether you’re accessing state/city/zip-level or regional data. See the following two sections for the set of valid statistic names available for each.

State/City/ZIP Statistics

Some of the most common statistics:

Price:MEDIAN
Inventory:TOTAL
DaysOnMarket:MEDIAN
PricePerSqft:MEDIAN

The full set of stats is available upon request - contact sales@altosresearch.com for details.

Regional Statistics

Some of the most common statistics:

Price:MEDIAN
Inventory:TOTAL
DaysOnMarket:MEDIAN
PricePerSqft:MEDIAN

The full set of stats is available upon request - contact sales@altosresearch.com for details.

Residence Type

All of our data is categorized by residence type, either as single family homes or condo/townhome. Both our charting and stats APIs require you to specify this option using the ‘rt=’ URL parameter. The possible values are:

sf: Single family home
mf: Condo or townhouse
co: Co-Op which is only valid for Manhattan ZIP codes (1000 - 10021)
sf,mf: Include both single family and condo (charting only)

Rolling Average

All of our charts and stats data is calculated using one of two rolling average values - either 7-day or 90-day. The 7-day rolling average will give you the real-time values, while the 90-day rolling average will provider smoother trends. The rolling average is a required URL parameter for both charts and stats APIs and should be specified using the ‘ra=’ parameter.

Use the 7-day rolling average for real-time values.

a: Seven-day rolling average
c: Ninety-day rolling average
a,c: Comparison of seven and ninety-day averages (charting only)

Quartile

Common question: "How do you determine the quartiles?" Easy answer: "We take the total number of homes on the market and divide by four." The parameter name for the quartile in a URL is 'q='.

t: The top (25% most expensive properties) quartile
u: The upper middle quartile
l: The lower middle quartile
b: The bottom quartile (25% least expensive properties)
a: The "average" quartile (all properties)
t,u,l,b: Combinations supported to compare quartile values (charting only)

Style/CSS Overrides

Serverl of our API-based services all the user to override the default CSS/style information used to render the output. This feature is available in our stat service (service=stat), regional stat service (srvice=zrstat), stat table service (service=statTable), and our AltosConnect Registration widget (service=crm).

To override the default CSS settings, you'll need to create and upload your custom CSS file to your server. Once uploaded, you can then use the 'css=' parameter of the API URL to specify the location of your CSS file.

To override the CSS of the AltosConnect registration widget, you would take the following <ifram> url:

http://www.altosresearch.com/altos/app?service=crm&pai=123&l=b

And append to it the location of your CSS file, as in:

http://www.altosresearch.com/altos/app?service=crm&pai=123&l=b&css=http://www.myserver.com/connect.css

To help you get started, you can use one of our standard AltosConnect CSS files:

blog layout (l=b): http://www.altosresearch.com/altos/css/crm/default/200px.css
medium layout (l=m): http://www.altosresearch.com/altos/css/crm/default/150px.css
wide layout (l=w): http://www.altosresearch.com/altos/css/crm/default/500px.css

Chart API

The following set of options applies only to charts - state/city/zip as well as regional.

Chart Size

This attribute applies only to charts, and is specified using the ‘sz=’ URL parameter. Must be one of the following:

t: Tiny. 150px wide x 100px high
s: Small. 240px wide x 160px high
b: Blog. 180px wide x 120px high
i: Intermediate. 360px wide x 240px high
m: Medium. 480px wide x 320px high
l: Large. 600px wide x 320px high
p: Poster. 1500px wide x 1000px high (Good for large screen displays)
r: Print. 3000px wide x 1500px high. (Good for print and high-resolution renderings)

Chart Timespan

All charts include the most recent data available. You can use the timespan parameter to select how many days of historical data to include. This is specified using the ‘ts=’ URL parameter and must be one of the following:

a: 30 days
b: 60 days
c: 90 days
d: 180 days
e: 360 days
z: Unlimited (This option will chart all historical data available)

Start/End Date

In place of a timespan, you can specify a start and end date for your chart instead. The values must be formatted in ISO format: YYYY-MM-DD. Use the ‘startDate=’ and ‘endDate=’ options on the URL:

startDate=2010-01-01&endDate=2010-12-31

No Title

By default, all of our charts include a title embedded in the generated PNG image. If you would prefer to provide your own title information in the surrounding HTML, you can disable the graphical titles with the ‘nt=’ parameter:

nt=true

Show Gaps

Although we strive to always provide the most complete data, there are times when we’ll have small gaps or outages in our coverage. Normally, the charting engine will ‘connect the dots’ between missing data points. If you’d prefer to disable this behavior, you can specify this using the ‘sg=’ parameter in the URL:

sg=true

Comparison Offset

Our charting API offers the ability to compare ranges in time. If you wanted to compare the most current data to the same data from one year ago, you could do this using a comparison offset of ‘52’ for ‘52 weeks’.

co=52

We allow you to compare date ranges up to 4 years - ‘co=408’.

Show Date

By default, our charts will display the data stamp of the most recent data point contained in the chart. If you’re prefer to disable this option, you can do so with the ‘sd=’ URL parameter:

sd=f

Show Copyright

By default, our charts will display a small Copyright message from Altos Research. If you’re prefer to disable this option, you can do so with the ‘sc=’ URL parameter:

sc=f

Chart Themes

We now support multiple chart themes. The original theme is named 'altos' and the newer is 'newchart'. You can specify the theme you want using:

theme=newchart

Example 'newchart' theme:

Example 'altos' theme:

Stats API

Below are a few options that are specific to the stats API (not available in charts).

Date Option

With our stats APIs, you can specify an individual date to retrieve values for. The date must be formatted in ISO format: YYYY-MM-DD. You specify the date option using the ‘d=’ URL parameter:

d=2010-12-05

Listing History Data API

This API can be used to obtain a JSON-formatted output of the listing history for a property specified by address, city, state and zip code. For example, to obtain the listing history data for the property at "800 CALIFORNIA" in Sunnyvale CA 94086, you would use the following URL:

http://data.altosresearch.com/altos/app?pai=100&apiv=1&service=listinghistory&st=CA&c=SUNNYVALE&z=94086&addr=800%20CALIFORNIA

In general, it is best to specify the address as simply the street number ("800") and street name ("CALIFORNIA") to ensure the greatest likelyhood of matches. You can also specify two optional parameters, start_date and end_date (both formatted as 'YYYY-MM-DD') to specify the time window over for the search. The earliest useful date is currently 2007-05-01, and varies depending on the market.

The JSON response has the following format:

{

"list": [

{

"unit_number": "",

"property_id": "a08373408624b1570ff6aafb77498308",

"baths": "1.00",

"zip": "94086",

"geocode_accuracy": "",

"residence_sqft": "765",

"year_built": "1942",

"street_name": "CALIFORNIA",

"state": "CA",

"lot_sqft": "4900",

"data_capture_date": "2011-08-26",

"city": "SUNNYVALE",

"days_on_market": "",

"price": "388000",

"beds": "2.00",

"street_address_raw": "800 E CALIFORNIA AV",

"street_direction": "EAST",

"longitude": "",

"street_number": "800",

"latitude": "",

"listing_entry_id": "caf478d031f90abd0131fe7caff77ea7",

"residence_type": "single_family",

"street_type": "AVENUE"

}

"responseCode": 200,

"apiVersion": 1

}

Listing History Chart API

Listing Comps API

This API can be used to obtain the current ‘comparable’ listing entries for a specific state/city/zip and residence type. The minimum set of required parameters are: partner ID, state, city, zip and residence type (see the API overview section for a full definition of thse parameters). For example:

http://data.altosresearch.com/altos/app?pai=100&apiv=1&rf=csv&service=listingcomps&st=CA&c=SUNNYVALE&z=94086&rt=sf

The results will be formatted as a CSV file. This particular API also supports the following optional parameters. Most of these parameters are mean to allow you to provide the API with the attributes of the property you are comparing against. When supplied, the API will then include that information in the output to allow for easier comparisons.

pid: property id - your identified for the comparison property
prt: property residence type - the residence type of the comparison property.
addr: property address - the street address of the comparison property.
beds: number of beds in the comparison property
baths: number of baths in the comparison property
sqft: number of sqft in the comparison property
v: value - the value/price of the comparison property
ip: include property details - ‘every’ or ‘first’. When you specify ‘ip=first’ the CSV results will include your property details as the first line of output in the CSV file. If you specify ‘ip=every’ the CSV results will include the property detail on every line of the output as the first set of columns.

Coverage APIs

The following set of APIs are designed to provide information on the locations that we provide data for. The output format is XML unless otherwise specified.

List Market Areas

A list of all market areas that we cover, in XML format:

http://stats.altosresearch.com/altos/app?service=listmarketareas

Sample XML output:

</markets>

List Markets, Counties, Cities, ZIPs as CSV

A CSV-formatted file of all of our covered locations. The last column ("stats_enabled") indicates whether we currently have stats data available for that ZIP code. This list is refreshed each week:

http://www.altosresearch.com/customer/coverage.csv

To get the list of only those ZIPs that have have stats available, you can instead retrieve this URL:

http://www.altosresearch.com/customer/enabled.csv

List Market Areas/Cities/ZIPs

An XML formatted heirarchy of market areas, cities and ZIP codes covered in our data

http://stats.altosresearch.com/altos/app?service=listmarketareacityzips

Sample XML output:

</city>

</market>

</markets>

Can't find what you're looking for? Need some extra guidance? We're here to help. Send a note to support@altosresearch.com and we'll be in touch right away.