The location endpoint is used to retrieve detailed geographic location information. This information can be useful for various purposes, from populating navigation selections in user interfaces to performing geospatial analysis.
This endpoint conforms to Houski API's standard filtering and sorting functionality.
To see all the fields that can be filtered or sorted by, see the fields page.
| Name | Required | Type | Description |
|---|---|---|---|
| api_key | Yes | UUID v4 | Authorization API key |
| community | No | String | A community within the city |
| city | No | String | A city within the province |
| province_abbreviation | No | String | A province abbreviation within the country |
| country_abbreviation | No | String | A country abbreviation |
| flat | No | Boolean (default: for_sale_source) | Return data in a flat data structure |
| resolution | No | String | The finest level of location data to be returned (must be 'country', 'province', 'city' or 'community'). |
Type declarations are available at the bottom of this page.
| Name | Type | Description |
|---|---|---|
| cache_hit | Boolean | Indicates if the data was retrieved from the cache |
| cost_cents | Number | Cost of the API call in cents |
| data | Object | Contains the location data in 'nested' and 'flat' sub-objects (for determinism) |
| error | String | Details about the error. Empty if no error |
| is_nested | Boolean | Indicates if the returned data is nested |
| is_flat | Boolean | Indicates if the returned data is flat |
| pagination | Object | Pagination information |
| price_quote | Boolean | Request is for a price quote |
| result_total | Number | Total number of results |
| time_ms | Number | Time taken for the request to complete in milliseconds |
Select the programming language you want to display the code examples in.
By default, location endpoint responses are returned in a nested format.
curl -X GET "https://api.houski.ca/location?api_key=YOUR_API_KEY&city=calgary&community_regex=(?i)^ra&country_abbreviation=ca&province_abbreviation=ab"
const houski_location_data_nested = async (): Promise<LocationResponse> => {
// You must copy the LocationResponse type declarations from the
// Houski API documentation to strongly type the response
const url = new URL('https://api.houski.ca/location');
url.searchParams.set('api_key', 'YOUR_API_KEY');
url.searchParams.set('city', 'calgary');
url.searchParams.set('community_regex', '(?i)^ra');
url.searchParams.set('country_abbreviation', 'ca');
url.searchParams.set('province_abbreviation', 'ab');
const response = await fetch(url);
const data = await response.json();
return data;
}
(async () => {
let data: LocationResponse = await houski_location_data_nested();
// Log the response
console.log(data);
})();
{
"cache_hit": true,
"cost_cents": 0.007199999876320362,
"data": {
"flat": [],
"nested": {
"countries": [
{
"abbreviation": "CA",
"id": "9ace2b6431b7f1be",
"link": "ca",
"name": "Canada",
"provinces": [
{
"abbreviation": "AB",
"cities": [
{
"communities": [
{
"id": "e4ea09d684accf91",
"link": "ca/ab/calgary/ramsay",
"name": "Ramsay",
"slug": "ramsay"
},
{
"id": "7244c981dd55f8d5",
"link": "ca/ab/calgary/ranchlands",
"name": "Ranchlands",
"slug": "ranchlands"
},
{
"id": "8223002a6144bb48",
"link": "ca/ab/calgary/range-view",
"name": "Range View",
"slug": "range-view"
},
{
"id": "b67fb29c420a316e",
"link": "ca/ab/calgary/rangeview",
"name": "Rangeview",
"slug": "rangeview"
}
],
"id": "6ec95b53075d062c",
"link": "ca/ab/calgary",
"name": "Calgary",
"slug": "calgary"
}
],
"id": "aae1f05a0f89d2c7",
"link": "ca/ab",
"name": "Alberta",
"slug": "alberta"
}
],
"slug": "canada"
}
]
}
},
"error": "",
"is_flat": false,
"is_nested": true,
"pagination": {
"current_page": 0,
"has_next_page": false,
"has_previous_page": false,
"page_total": 0
},
"price_quote": false,
"result_total": 4,
"time_ms": 390
}
curl -X GET "https://api.houski.ca/location?api_key=YOUR_API_KEY&city=calgary&community_regex=(?i)^ra&country_abbreviation=ca&flat=true&province_abbreviation=ab"
const houski_location_data_flat = async (): Promise<LocationResponse> => {
// You must copy the LocationResponse type declarations from the
// Houski API documentation to strongly type the response
const url = new URL('https://api.houski.ca/location');
url.searchParams.set('api_key', 'YOUR_API_KEY');
url.searchParams.set('city', 'calgary');
url.searchParams.set('community_regex', '(?i)^ra');
url.searchParams.set('country_abbreviation', 'ca');
url.searchParams.set('flat', 'true');
url.searchParams.set('province_abbreviation', 'ab');
const response = await fetch(url);
const data = await response.json();
return data;
}
(async () => {
let data: LocationResponse = await houski_location_data_flat();
// Log the response
console.log(data);
})();
{
"cache_hit": false,
"cost_cents": 0.007199999876320362,
"data": {
"flat": [
{
"city": "Calgary",
"city_id": "6ec95b53075d062c",
"city_link": "ca/ab/calgary",
"city_slug": "calgary",
"community": "Ramsay",
"community_id": "e4ea09d684accf91",
"community_link": "ca/ab/calgary/ramsay",
"community_slug": "ramsay",
"country": "Canada",
"country_abbreviation": "CA",
"country_abbreviation_id": "9ace2b6431b7f1be",
"country_abbreviation_link": "ca",
"country_slug": "canada",
"province": "Alberta",
"province_abbreviation": "AB",
"province_abbreviation_id": "aae1f05a0f89d2c7",
"province_abbreviation_link": "ca/ab",
"province_slug": "alberta"
},
{
"city": "Calgary",
"city_id": "6ec95b53075d062c",
"city_link": "ca/ab/calgary",
"city_slug": "calgary",
"community": "Ranchlands",
"community_id": "7244c981dd55f8d5",
"community_link": "ca/ab/calgary/ranchlands",
"community_slug": "ranchlands",
"country": "Canada",
"country_abbreviation": "CA",
"country_abbreviation_id": "9ace2b6431b7f1be",
"country_abbreviation_link": "ca",
"country_slug": "canada",
"province": "Alberta",
"province_abbreviation": "AB",
"province_abbreviation_id": "aae1f05a0f89d2c7",
"province_abbreviation_link": "ca/ab",
"province_slug": "alberta"
},
{
"city": "Calgary",
"city_id": "6ec95b53075d062c",
"city_link": "ca/ab/calgary",
"city_slug": "calgary",
"community": "Range View",
"community_id": "8223002a6144bb48",
"community_link": "ca/ab/calgary/range-view",
"community_slug": "range-view",
"country": "Canada",
"country_abbreviation": "CA",
"country_abbreviation_id": "9ace2b6431b7f1be",
"country_abbreviation_link": "ca",
"country_slug": "canada",
"province": "Alberta",
"province_abbreviation": "AB",
"province_abbreviation_id": "aae1f05a0f89d2c7",
"province_abbreviation_link": "ca/ab",
"province_slug": "alberta"
},
{
"city": "Calgary",
"city_id": "6ec95b53075d062c",
"city_link": "ca/ab/calgary",
"city_slug": "calgary",
"community": "Rangeview",
"community_id": "b67fb29c420a316e",
"community_link": "ca/ab/calgary/rangeview",
"community_slug": "rangeview",
"country": "Canada",
"country_abbreviation": "CA",
"country_abbreviation_id": "9ace2b6431b7f1be",
"country_abbreviation_link": "ca",
"country_slug": "canada",
"province": "Alberta",
"province_abbreviation": "AB",
"province_abbreviation_id": "aae1f05a0f89d2c7",
"province_abbreviation_link": "ca/ab",
"province_slug": "alberta"
}
],
"nested": {
"countries": []
}
},
"error": "",
"is_flat": true,
"is_nested": false,
"pagination": {
"current_page": 0,
"has_next_page": false,
"has_previous_page": false,
"page_total": 0
},
"price_quote": false,
"result_total": 4,
"time_ms": 445
}
interface LocationResponse {
cache_hit: boolean;
cost_cents: number;
data: LocationData;
error: string;
is_nested: boolean;
is_flat: boolean;
pagination: Pagination;
price_quote: boolean;
result_total: number;
time_ms: number;
}
interface LocationData {
nested: NestedLocation;
flat: FlatLocation[];
}
interface NestedLocation {
countries: CountryNested[];
}
interface CountryNested {
name: string;
link: string;
id: string;
abbreviation: string;
slug: string;
provinces: ProvinceNested[];
}
interface ProvinceNested {
name: string;
link: string;
id: string;
abbreviation: string;
slug: string;
cities: CityNested[];
}
interface CityNested {
name: string;
link: string;
slug: string;
id: string;
communities: CommunityNested[];
}
interface CommunityNested {
name: string;
slug: string;
id: string;
link: string;
}
interface FlatLocation {
city_id?: string | null;
city_link?: string | null;
city_slug?: string | null;
city?: string | null;
community_id?: string | null;
community_link?: string | null;
community_slug?: string | null;
community?: string | null;
country_abbreviation?: string | null;
country_abbreviation_id?: string | null;
country_abbreviation_link?: string | null;
country_slug?: string | null;
country?: string | null;
province_abbreviation?: string | null;
province_abbreviation_id?: string | null;
province_abbreviation_link?: string | null;
province_slug?: string | null;
province?: string | null;
}
interface Pagination {
current_page: number;
has_next_page: boolean;
has_previous_page: boolean;
page_total: number;
}