!

/location

GET
https://api.houski.ca/location

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.

Example use cases

You can find examples for common use cases on our recipes page.
  1. Dropdown for country, province, city and community selection in a user interface.
  2. Use filters to display countries, provinces, cities and communities based on user preferences, like price range.
  3. The location endpoint returns formatted links and slugs for linking to other Houski resources.
  4. For market analysis, use this endpoint to get location lists by region, then query /properties or /map for relevant data.

Request parameters

NameRequiredTypeDescription
api_keyYesUUID v4Authorization API key
communityNoStringA community within the city
cityNoStringA city within the province
province_abbreviationNoStringA province abbreviation within the country
country_abbreviationNoStringA country abbreviation
flatNoBoolean (default: true)Return data in a flat data structure
resolutionNoStringThe finest level of location data to be returned (must be 'country', 'province', 'city' or 'community').

Response object

Type declarations are available at the bottom of this page.

NameTypeDescription
cache_hitBooleanIndicates if the data was retrieved from the cache
cost_centsNumberCost of the API call in cents
dataObjectContains the location data in 'nested' and 'flat' sub-objects (for determinism)
errorStringDetails about the error. Empty if no error
is_nestedBooleanIndicates if the returned data is nested
is_flatBooleanIndicates if the returned data is flat
paginationObjectPagination information
price_quoteBooleanRequest is for a price quote
result_totalNumberTotal number of results
time_msNumberTime taken for the request to complete in milliseconds

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": true,
  "cost_cents": 0.00419999985024333,
  "data": {
    "flat": [],
    "nested": {
      "countries": [
        {
          "abbreviation": "CA",
          "link": "ca",
          "name": "Canada",
          "provinces": [
            {
              "abbreviation": "AB",
              "cities": [
                {
                  "communities": [
                    {
                      "link": "ca/ab/calgary/ramsay",
                      "name": "Ramsay",
                      "slug": "ramsay"
                    },
                    {
                      "link": "ca/ab/calgary/ranchlands",
                      "name": "Ranchlands",
                      "slug": "ranchlands"
                    },
                    {
                      "link": "ca/ab/calgary/rangeview",
                      "name": "Rangeview",
                      "slug": "rangeview"
                    }
                  ],
                  "link": "ca/ab/calgary",
                  "name": "Calgary",
                  "slug": "calgary"
                }
              ],
              "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": 601
}
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.00419999985024333,
  "data": {
    "flat": [
      {
        "city": "Calgary",
        "city_id": null,
        "city_link": "ca/ab/calgary",
        "city_slug": "calgary",
        "community": "Ramsay",
        "community_id": null,
        "community_link": "ca/ab/calgary/ramsay",
        "community_slug": "ramsay",
        "country": "Canada",
        "country_abbreviation": "CA",
        "country_abbreviation_id": null,
        "country_abbreviation_link": "ca",
        "country_slug": "canada",
        "province": "Alberta",
        "province_abbreviation": "AB",
        "province_abbreviation_id": null,
        "province_abbreviation_link": "ca/ab",
        "province_slug": "alberta"
      },
      {
        "city": "Calgary",
        "city_id": null,
        "city_link": "ca/ab/calgary",
        "city_slug": "calgary",
        "community": "Ranchlands",
        "community_id": null,
        "community_link": "ca/ab/calgary/ranchlands",
        "community_slug": "ranchlands",
        "country": "Canada",
        "country_abbreviation": "CA",
        "country_abbreviation_id": null,
        "country_abbreviation_link": "ca",
        "country_slug": "canada",
        "province": "Alberta",
        "province_abbreviation": "AB",
        "province_abbreviation_id": null,
        "province_abbreviation_link": "ca/ab",
        "province_slug": "alberta"
      },
      {
        "city": "Calgary",
        "city_id": null,
        "city_link": "ca/ab/calgary",
        "city_slug": "calgary",
        "community": "Rangeview",
        "community_id": null,
        "community_link": "ca/ab/calgary/rangeview",
        "community_slug": "rangeview",
        "country": "Canada",
        "country_abbreviation": "CA",
        "country_abbreviation_id": null,
        "country_abbreviation_link": "ca",
        "country_slug": "canada",
        "province": "Alberta",
        "province_abbreviation": "AB",
        "province_abbreviation_id": null,
        "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": 607
}

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;
    abbreviation: string;
    slug: string;
    provinces: ProvinceNested[];
}

interface ProvinceNested {
    name: string;
    link: string;
    abbreviation: string;
    slug: string;
    cities: CityNested[];
}

interface CityNested {
    name: string;
    link: string;
    slug: string;
    communities: CommunityNested[];
}

interface CommunityNested {
    name: string;
    slug: 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;
}