Introduction
Welcome to the Altos Research Intel API! You can use our API to access the latest real estate market data, and historical data, brought to you by Altos Research.
Authentication
To confirm your api keys authorization, use the following:
import requests
resp = requests.get(
"https://intel.altosresearch.com/api/authorized",
auth=("altosintel_abcdefghijklmn1234567890", "")
)
print(resp.json())
# {'message': 'logged in'}
import requests
resp = requests.get(
"https://intel.altosresearch.com/api/authorized",
auth=("altosintel_abcdefghijklmn1234567890", "")
)
print(resp.json())
# {'message': 'logged in'}
curl \
-u altosintel_abcdefghijklmn1234567890: \
https://intel.altosresearch.com/api/authorized
# {"message":"logged in"}
const API_KEY = "altosintel_abcdefghijklmn1234567890:";
const Authorization = `Basic ${btoa(API_KEY)}`;
const resp = await fetch("https://intel.altosresearch.com/api/authorized", {
headers: { Authorization },
});
await resp.json();
// { message: "logged in" }
var apiURL = "https://intel.altosresearch.com/api/authorized";
var apiKey = "altosintel_abcdefghijklmn1234567890";
var apiAuthorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
"Basic",
Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes($"{apiKey}:"))
);
var client = new System.Net.Http.HttpClient();
client.DefaultRequestHeaders.Authorization = apiAuthorization;
var resp = client.GetAsync(apiURL).Result;
var responseString = await resp.Content.ReadAsStringAsync();
// "{\n \"message\": \"logged in\"\n}\n"
Make sure to replace
altosintel_abcdefghijklmn1234567890with your API key.
Altos Intel requires the API key be passed in every request via Basic Authentication:
Authorization: Basic <credentials>
where credentials is the Base64 encoding of the api key followed by :, as seen in the code samples.
Download Intel File
To download a specific file, use the following:
import requests
AUTH = ("altosintel_abcdefghijklmn1234567890", "")
params = {
"date": "2022-01-21",
"region": "us_national",
"type": "listings",
}
resp = requests.get(
"https://intel.altosresearch.com/api/data",
auth=AUTH, params=params
)
import requests
import pandas as pd
AUTH = ("altosintel_abcdefghijklmn1234567890", "")
params = {
"date": "2022-01-21",
"region": "us_national",
"type": "listings",
}
resp = requests.get(
"https://intel.altosresearch.com/api/data",
auth=AUTH, params=params, stream=True
)
pd.read_csv(resp.raw, compression="gzip")
curl -L \
-u altosintel_abcdefghijklmn1234567890: \
"https://intel.altosresearch.com/api/data?date=2021-12-24&type=rental®ion=us_national" \
-o us_national_rentals_2021-12-24.csv.gz
const API_KEY = "altosintel_abcdefghijklmn1234567890:";
const Authorization = `Basic ${btoa(API_KEY)}`;
let qs = new URLSearchParams({
date: "2022-01-21",
region: "us_national",
type: "listings",
});
const resp = await fetch(`https://intel.altosresearch.com/api/data?${qs}`, {
headers: { Authorization },
});
await resp.text();
var apiURL = "https://intel.altosresearch.com/api/data?date=2022-01-21®ion=us_national&type=listings";
var apiKey = "altosintel_abcdefghijklmn1234567890";
var apiAuthorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
"Basic",
Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes($"{apiKey}:"))
);
var client = new System.Net.Http.HttpClient();
client.DefaultRequestHeaders.Authorization = apiAuthorization;
var resp = client.GetAsync(apiURL).Result;
var responseString = await resp.Content.ReadAsStringAsync();
Make sure to replace
altosintel_abcdefghijklmn1234567890with your API key.
This end point redirects to a specific data file that can be downloaded.
HTTP Request
GET https://intel.altosresearch.com/api/data
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| date | Required | Must be a friday. Many of our data sets go back to 2011. |
| region | Required | Name of region. |
| type | listings | See types. |
| columnset | classic | See schema. |
List Intel Files
import requests
AUTH = ("altosintel_abcdefghijklmn1234567890", "")
params = {
"region": "us_national",
"type": "listings",
"limit": 5,
}
resp = requests.get(
"https://intel.altosresearch.com/api/list",
auth=AUTH, params=params
)
resp.json()
import requests
AUTH = ("altosintel_abcdefghijklmn1234567890", "")
params = {
"date": "2022-01-21",
"region": "us_national",
"limit": 5,
}
resp = requests.get(
"https://intel.altosresearch.com/api/list",
auth=AUTH, params=params
)
resp.json()
curl -L \
-u altosintel_abcdefghijklmn1234567890: \
"https://data.altos.re/api/list?date=2021-12-24&type=rentals®ion=us_national&limit=5"
const API_KEY = "altosintel_abcdefghijklmn1234567890:";
const Authorization = `Basic ${btoa(API_KEY)}`;
let qs = new URLSearchParams({
date: "2022-01-21",
region: "us_national",
type: "listings",
});
const resp = await fetch(`https://intel.altosresearch.com/api/list?${qs}`, {
headers: { Authorization },
});
await resp.text();
var apiURL = "https://intel.altosresearch.com/api/list";
var apiKey = "altosintel_abcdefghijklmn1234567890";
var apiAuthorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
"Basic",
Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes($"{apiKey}:"))
);
var client = new System.Net.Http.HttpClient();
client.DefaultRequestHeaders.Authorization = apiAuthorization;
var resp = client.GetAsync(apiURL).Result;
var responseString = await resp.Content.ReadAsStringAsync();
// "{\n \"message\": \"logged in\"\n}\n"
The above command returns JSON structured like this:
[
{
"filename": "us_national_listings_classic_2022-01-28.csv.gz",
"filesize": 28923186,
"collection": "listings",
"column_set": "classic",
"date": "2022-01-28",
"ext": "csv.gz"
},
...
]
This endpoint returns all the files available in the account.
HTTP Request
GET https://intel.altosresearch.com/api/list
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| type | listings | |
| region | us_national | |
| column_set | classic | |
| range | 999 |
Schema
Type
| Type | Description |
|---|---|
| listings | Active listings. |
| listings-new | The subset of active listings which have been on the market less than a week. |
| listings-absorbed | The subset of the previous week's active listings which are not in this week's. |
| pendings | Pendings e.g. under contract. |
| rentals | Active rental listings. |
| stats | Trends file of statistics across zip codes and cities in the US. |
Region
Can be us_national or state_county-name.
Active Listings
These are the active listings for sale in the market.
classic
| Column name | Description |
|---|---|
| date | Date seen |
| property_id | Unique id for the property |
| listing_id | Unique id for the listing |
| parcel_number | Assessor's parcel number |
| county_fips_code | Five digit fips code for county |
| street_address | Street address, may include unit |
| city | City name |
| state | State two letter abbr |
| zip | Zipcode |
| price | Price of listing |
| type | e.g. single_family or multi_family |
| beds | Number of beds |
| baths | Number of baths |
| floor_size | Sqft inside |
| lot_size | Sqft of lot |
| built_in | Year property was built |
| geo_lat | Latitude |
| geo_long | Longitude |
Pendings
These are the listings which have an offer that has been accepted by the buyer. The sale may fall through, in which case we may see it back in the active listings set.
classic
| Column name | Description |
|---|---|
| date | Date seen |
| property_id | Unique id for the property |
| listing_id | Unique id for the listing |
| parcel_number | Assessor's parcel number |
| county_fips_code | Five digit fips code for county |
| street_address | Street address, may include unit |
| city | City name |
| state | State two letter abbr |
| zip | Zipcode |
| price | Price of listing |
| type | e.g. single_family or multi_family |
| beds | Number of beds |
| baths | Number of baths |
| floor_size | Sqft inside |
| lot_size | Sqft of lot |
| built_in | Year property was built |
| geo_lat | Latitude |
| geo_long | Longitude |
Rentals
These are rental listings available in the market.
classic
| Column name | Description |
|---|---|
| date | Date seen |
| property_id | Unique id for the property |
| community_id | Unique id for the listing |
| property_name | ?? |
| parcel_number | Assessor's parcel number |
| unit_id | Year property was built |
| unit_name | Year property was built |
| street_address | Street Address |
| city | City name |
| state | State, unabbreviated |
| zip | Zipcode |
| price | Price of pending (may not be the sold price) |
| type | e.g. single_family or multi_family |
| beds | Number of beds |
| baths | Number of baths |
| floor_size | Sqft inside |
| built_in | Sqft of lot |
| geo_lat | Latitude |
| geo_long | Longitude |
| laundry_in_unit | |
| cats_allowed | |
| dogs_allowed | |
| patio_or_balcony | |
| air_conditioning | |
| pool | |
| fitness_center | |
| on_street_parking | |
| off_street_parking | |
| garage_parking |
Stats
Our trends file includes many aggregated statistics by zip code and city across the US.
They're are also available by MSA, state and nationwide.
Filename
classic
| Column name | Description |
|---|---|
| date | Date seen |
| state | State two letter abbr |
| city | City name |
| zip | Zipcode |
| res_type | e.g. single_family or multi_family |
| quartile | ALL, FIRST, SECOND, THIRD, or FOURTH |
| rolling_average | 7-day or 90-day statistic |
| age_mean | |
| apartment_rental_price_median | |
| baths_mean | |
| beds_mean | |
| days_on_market_mean | |
| days_on_market_median | |
| estimated_sales_total | |
| house_rental_price_median | |
| inventory_total | |
| listings_absorbed_total | |
| magnitude_price_decreased_median | |
| magnitude_price_increased_median | |
| market_action_median | |
| months_of_inventory_median | |
| new_listings_total | |
| percent_price_decreased_median | |
| percent_price_increased_median | |
| price_max | |
| price_median | |
| price_min | |
| price_of_listings_absorbed_median | |
| price_of_new_listings_median | |
| rental_price_median | |
| sqft_median |
Errors
The Altos Research Intel API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 401 | Unauthorized -- Your API key is wrong or has been disabled |
| 403 | Forbidden -- You're not subscribed to the specified file or region. |
| 404 | Not Found -- The resource or the specified file or region could not be found. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |