Geography

The Rapid Geography APIs provide you with access to geographic definitions and property mappings for over 600,000 regions and airports.

Regions

Returns the geographic definition and property mappings of regions matching the specified parameters.

To request all regions in the world, omit the ancestor query parameter. To request all regions in a specific continent, country or other level, specify the ID of that region as the ancestor. Refer to the list below of top level regions.

Region

Returns the geographic definition and property mappings for the requested Region ID.

Use this API to retrieve geography information and property mappings for a known Region ID.

Get properties within geography definition

Returns the properties within a custom polygon based on your geography definitions.

Use this API to build out your property mapping database if you maintain your own geography definitions and do not use the Rapid API geography regions. Easily map properties to your geography definitions for areas such as multi-cities, cities, and neighborhoods.

Three search parameters allow travelers to further filter their results and be more precise in their search.

supply_source: Indicates whether properties are sourced from Expedia or Vrbo. If not included this filter will default to supply_source=expedia.
country_code: Allows filtering of results by country.
type: Explains the geographic entity represented such as city or neighborhood.
country_subdivision_code: Allows filtering to the ISO 3166-2 country subdivision.
area: Allows searching by geography. More information below.

Additional reference information

Region types

The type object explains the geographic entity represented, such as city or neighborhood. Refer to the list of region types for detailed descriptions.

Area

The area object can be used in conjunction with a kilometer radius and either central latitude/longitude coordinates or the border of a region.

Radius combined with region_id would search an area that extends the number of kilometers specified from the boundaries of the region in all directions.
Radius combined with a single point, specified by a latitude/longitude pair, would search an area in a circle with the specified kilometer radius.
Radius should be specified in non-negative whole kilometers. Decimals will generate an error. A radius of 0 is allowed.

Restrictions

When specifying the area parameter, there will be a limit of 100 results, which can be narrowed further by the limit parameter.
Due to the number of results, unless point_of_interest is specified as the only type, regions of type point_of_interest will not be included in a request that filters to an area.
If point_of_interest is provided along with other types, point_of_interest will be ignored (with no error) and all other type selections will be applied.

Examples:

Airport search within 50km of a lat/long:

type=airport&limit=3&area=50,37.227924,93.310036

Region ID area search for city type with a limit of 3 and 5km area:

&area=5,602962&supply_score=expedia&type=city&limit=3

Country subdivision code

Filter results down to only the ISO 3166-2 country subdivision, for example US-MO. country_subdivision_code is both a field and a search parameter.

Example:

Region search by ISO code:

country_subdivision_code =US-MO

Localization

The language object only uses hyphenated pairs of two-digit language and country codes, see the list of available language options. Review our supported languages before integrating any codes. Only the name and name_full fields in the responses are provided in the requested language. All other geography definitions in the response will be in English.

Polygons

The bounding_polygon object provides the list of coordinates that encompass the shape of the region. Regions can cover areas represented by either a single polygon or multiple polygons. Region types that are represented by a single coordinate (such as point of interest, train station, or airport) do not have a bounding polygon.

The bounding_polygon object follows the GeoJSON standard with the longitude value listed first followed by latitude when providing lists of coordinates.

Associations between regions

The touristic relationship between regions is provided using the associations object. Within the associations object, we model:

Associated city for regions of type airport. This allows you to recommend a destination for any particular airport.
Top points of interest for a given region. This allows you to recommend places to visit when a traveler is visiting a particular region, such as California, London, or Brooklyn.

Hierarchy between regions

The relationship between regions is provided using the ancestors and descendants objects. Due to geographical and political variations throughout the world, region types do not have a strict hierarchy. Logically, however, a city is typically associated with a multi-city, province/state, or country. To derive the hierarchy of a specific region use the ancestors values.

ancestors: Represents the levels of hierarchy above a given region. For example, the direct ancestor of the multi-city of Athens, Greece is the region of Attica and further up the hierarchy its ancestors include Greece and Europe. A region may have more than one parent. Since the multi-city of Geneva is on the border of Switzerland and France, it will have ancestors in both countries.
descendants: Represents the levels of hierarchy below a given region. In our example, the city of Piraeus, Greece is a descendant of the multi-city of Athens, Greece. The descendants map within a region object only contains the direct children (one level down) of that region.

To provide more detailed information about geographical features, use tags and categories:

tags: Provide more granular detail around geographic features by describing them in a way that reflects how those features are named in real life. Examples include descriptions of activities (ski, racetrack etc.), attractions, civic areas, or geographic administrative areas like a canton, parish, or district.
categories: Create a globally applicable hierarchy of geographic features and are intended to offer comparable geography levels regardless of the governmental structure in any given country or region. Examples include continent, country, or province.

Note: If your implementation has multiple sources of supply, you'll need to layer them into the geography you want to use.

Example:

"categories": [
"place:administrative",
"administrative:country"
],
"tags": [
"geo-admin:country"
]

Property mappings for regions

Property mappings are provided for the Region and Regions API. Region types with property mappings are high_level_region, province_state, multi_city_vicinity, city, neighborhood, point_of_interest, and select countries. Property mappings are available in two include parameter options:

property_ids: This option provides only the properties within the region's polygon. The polygon is the bounding shape that represents the region’s area.
property_ids_expanded: If the region’s polygon does not contain at least 100 properties, this option provides the properties within the polygon in addition to properties within a 30km radius of the region. This expanded set of properties should ensure that enough properties are presented in property search results for a destination. For region types represented by a single coordinate rather than a polygon (e.g. a point of interest), only this expanded option will provide associated property mappings.

For larger region types (high_level_region, province_state, country, and continent), up to the top 500 properties will be returned. For a full list of properties in these regions, you'll need to request properties from each of the descendants which comprise the larger region.

Polygons are optimized to use search and transaction data and will expand smaller regions outside of the polygon where most relevant.

API details

Explore the geography-related endpoint definitions on this page, then use the API Explorer or another testing software to get an understanding of how the examples and schema definitions compare to the actual output.

Additional resources

Whether you're looking to try out all the Rapid API endpoints or to download its OpenAPI specs or our Postman collection, we have you covered.