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.
| Name | Required | Type | Description |
|---|---|---|---|
| api_key | Yes | UUID v4 | Your API key for authorization |
| 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: false) | 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 | Indicates whether the response is 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.
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": false,
"cost_cents": 0.005399999674409628,
"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": "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": 3,
"time_ms": 691
}
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.005399999674409628,
"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": "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": 3,
"time_ms": 866
}
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;
}