/location

GET

https://api.houski.ca/location

Returns geographic location data - good for navigation UIs and geospatial analysis.

Supports standard filtering. Results always come back ordered country, province, city, then community, so this endpoint takes no sort parameters.

Example use cases

Country, province, city, and community selection dropdowns.
Filter locations by user preferences like price range.
Get pre-built links and slugs to other Houski resources.
Market analysis: list regions, then query /properties or /map.

Request parameters

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	Finest level returned: 'country', 'province', 'city' or 'community'

This endpoint has no paging and returns every location that matches in one response. Narrow the response with resolution and the location parameters above.

This endpoint also supports field filters on any filterable property field, like community_regex or bedroom_gte. See the filtering documentation for details.

Response object

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	Integer	Cost of the API call in cents
data	Object	Holds location data in 'nested' and 'flat' sub-objects
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	Integer	Total number of results
time_ms	Integer	Time taken for the request to complete in milliseconds

LocationData object

Name	Type	Description
nested	NestedLocation	Location data organized in a hierarchical structure
flat	Array<FlatLocation>	Location data as a flat array of location objects

NestedLocation object

Name	Type	Description
countries	Array<CountryNested>	Countries with nested provinces, cities, and communities

CountryNested object

Name	Type	Description
name	String	Full country name
link	String	URL link to the country page
id	String	Unique identifier for the country
abbreviation	String	Country abbreviation (e.g., 'ca', 'us')
slug	String	URL-friendly slug for the country
provinces	Array<ProvinceNested>	Array of province objects within this country

ProvinceNested object

Name	Type	Description
name	String	Full province name
link	String	URL link to the province page
id	String	Unique identifier for the province
abbreviation	String	Province abbreviation (e.g., 'ab', 'bc')
slug	String	URL-friendly slug for the province
cities	Array<CityNested>	Array of city objects within this province

CityNested object

Name	Type	Description
name	String	Full city name
link	String	URL link to the city page
slug	String	URL-friendly slug for the city
id	String	Unique identifier for the city
communities	Array<CommunityNested>	Array of community objects within this city

CommunityNested object

Name	Type	Description
name	String	Full community name
slug	String	URL-friendly slug for the community
id	String	Unique identifier for the community
link	String	URL link to the community page

FlatLocation object

Name	Type	Description
city_id	String?	Unique identifier for the city
city_link	String?	URL link to the city page
city_slug	String?	URL-friendly slug for the city
city	String?	Full city name
community_id	String?	Unique identifier for the community
community_link	String?	URL link to the community page
community_slug	String?	URL-friendly slug for the community
community	String?	Full community name
country_abbreviation	String?	Country abbreviation (e.g., 'ca', 'us')
country_abbreviation_id	String?	Unique identifier for the country abbreviation
country_abbreviation_link	String?	URL link to the country page
country_slug	String?	URL-friendly slug for the country
country	String?	Full country name
province_abbreviation	String?	Province abbreviation (e.g., 'ab', 'bc')
province_abbreviation_id	String?	Unique identifier for the province abbreviation
province_abbreviation_link	String?	URL link to the province page
province_slug	String?	URL-friendly slug for the province
province	String?	Full province name

Pagination object

Name	Type	Description
page	Integer	Current page number (1-indexed)
has_next_page	Boolean	Indicates if there is a next page available
has_previous_page	Boolean	Indicates if there is a previous page available
page_total	Integer	Total number of pages available

Example requests and responses

Programming language

Select the programming language you want to display the code examples in.

Get location data in nested format

By default, location endpoint responses are returned in a nested format.

Request

Shell session

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"

TypeScript code

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);
})();

Response

JSON

{
  "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": 166
}

Get location data in flat format

Request

Shell session

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"

TypeScript code

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);
})();

Response

JSON

{
  "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": 168
}

Response type declarations

TypeScript code

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;
}

API Docs

Account

Data products

Industries

Explore

Company

Account

/location

Example use cases

Request parameters

Response object

LocationData object

NestedLocation object

CountryNested object

ProvinceNested object

CityNested object

CommunityNested object

FlatLocation object

Pagination object

Example requests and responses

Response type declarations