Airbnb API & Short-Term Rental Data API | AirROI (2.3.0)

This API is secured using an API key. To get your key, please visit www.airroi.com/api/developer/activate.

Include your assigned API key in the request headers as follows:

• Header Name: X-API-KEY
• Value: your-airroi-api-key

Example:

curl -X GET \
  -H "X-API-KEY: your-airroi-api-key" \
  https://api.airroi.com/listings?listing_id=1234567890

Our API provides powerful filtering capabilities to help you refine your search results and retrieve the exact data you need.

You can filter your results by providing a filter object in the request body. The filter object is a simple object where each field maps to its condition(s). Multiple filters are ANDed together.

For most fields, each field condition must contain exactly one operator.

The amenities field is the exception. It may combine all, any, and none in the same object:

• all: the listing must include every amenity in the list
• any: the listing must include at least one amenity in the list
• none: the listing must include none of the amenities in the list

If you provide more than one of these operators, the listing must satisfy all of them. For example, "amenities": {"all": ["wifi", "kitchen"], "any": ["pool", "hot_tub"], "none": ["smoking_allowed"]} means:

• the listing has wifi and kitchen
• the listing has pool or hot_tub
• the listing does not have smoking_allowed

Filter Operators

Operator	Description	Example
eq	Equal to	"bedrooms": {"eq": 2}
lt	Less than	"price": {"lt": 100}
lte	Less than or equal to	"price": {"lte": 100}
gt	Greater than	"rating": {"gt": 4.5}
gte	Greater than or equal to	"rating": {"gte": 4.5}
range	Between two values (inclusive)	"bedrooms": {"range": [2, 4]}
any	Contains any of the values in the list	"amenities": {"any": ["pool", "wifi"]}
all	Contains all of the values in the list	"amenities": {"all": ["pool", "wifi"]}
none	Contains none of the values in the list	"amenities": {"none": ["pets_allowed"]}

Powerful Filter Sort Example

Here's a comprehensive example showcasing multiple filters and sorts:

{
  "filter": {
    "room_type": {"eq": "entire_home"},
    "bedrooms": {"range": [2, 5]},
    "baths": {"gte": 2},
    "guests": {"range": [4, 10]},
    "amenities": {"all": ["wifi", "kitchen", "air_conditioning"], "any": ["pool", "hot_tub", "beach_access", "waterfront"], "none": ["pets_allowed", "smoking_allowed"]},
    "superhost": {"eq": true},
    "instant_book": {"eq": true},
    "min_nights": {"lte": 3},
    "rating_overall": {"gte": 4.8},
    "num_reviews": {"gte": 50},
    "ttm_revenue": {"range": [75000, 250000]},
    "ttm_occupancy": {"gte": 0.7},
    "ttm_avg_rate": {"range": [200, 800]},
    "l90d_occupancy": {"gt": 0.65},
    "cleaning_fee": {"lte": 200}
  },
  "sort": {
    "ttm_revenue": "desc",
    "rating_overall": "desc",
    "ttm_occupancy": "desc",
    "ttm_avg_rate": "asc",
    "num_reviews": "desc"
  },
  "pagination": {
    "page_size": 10,
    "offset": 0
  },
  "currency": "native"
}

This query finds high-performing entire homes that are family-friendly, have luxury amenities, excellent ratings, and strong financial performance, sorted by multiple criteria.

Location Filtering

Our location filtering is powerful and flexible, allowing you to search at various geographic levels. If you are unsure about the exact spelling of a location, you can use the /markets/search or /markets/lookup endpoints to find the correct location names.

Understanding Market Administrative Levels

• Country: The country where the property is located. (e.g., "US", "France")
• Region: The primary administrative division, such as a state or province. (e.g., "California", "Ile-de-France")
• Locality: The city, town, or other municipality. (e.g., "Los Angeles", "Paris")
• District: A neighborhood, borough, or other sub-city area. (e.g., "18th Arrondissement", "10001")

By Market

When searching for listings, you can specify a market object to narrow your search to a specific geographic area. The country, region, locality, and district fields are all optional, allowing for searches at different levels of granularity.

Global Search To search for listings globally, set the market object to null.

{
  "market": null,
  "sort": {
    "ttm_revenue": "desc"
  }
}

Country-Level Search To find high-performing entire home listings with excellent ratings in the United States:

{
  "market": {
    "country": "United States"
  },
  "filter": {
    "room_type": {"eq": "entire_home"},
    "ttm_revenue": {"gte": 75000},
    "ttm_occupancy": {"gt": 0.65},
    "rating_overall": {"gte": 4.8},
    "num_reviews": {"gte": 25}
  },
  "sort": {
    "ttm_revenue": "desc",
    "rating_overall": "desc",
    "ttm_occupancy": "desc"
  },
  "pagination": {
    "page_size": 10,
    "offset": 0
  }
}

Region-Level Search To find premium vacation rentals in California with specific amenities and performance metrics:

{
  "market": {
    "country": "United States",
    "region": "California"
  },
  "filter": {
    "bedrooms": {"range": [3, 6]},
    "baths": {"gte": 2.5},
    "guests": {"gte": 6},
    "amenities": {"all": ["pool", "hot_tub", "wifi", "kitchen"]},
    "ttm_avg_rate": {"range": [350, 1000]},
    "ttm_revenue": {"gt": 100000},
    "superhost": {"eq": true},
    "instant_book": {"eq": true}
  },
  "sort": {
    "ttm_revenue": "desc",
    "ttm_avg_rate": "desc",
    "num_reviews": "desc"
  },
  "currency": "usd"
}

Locality-Level Search To find high-performing short-term rentals in Miami Beach with beach proximity and luxury features:

{
  "market": {
    "country": "United States",
    "region": "Florida",
    "locality": "Miami Beach"
  },
  "filter": {
    "bedrooms": {"gte": 2},
    "baths": {"gte": 2},
    "amenities": {"all": ["beach_access", "patio_or_balcony", "pool", "free_parking_on_premises"]},
    "ttm_occupancy": {"gte": 0.70},
    "ttm_revenue": {"gte": 80000},
    "rating_overall": {"gte": 4.7},
    "instant_book": {"eq": true}
  },
  "sort": {
    "ttm_revenue": "desc",
    "ttm_occupancy": "desc"
  },
  "currency": "usd"
}

District-Level Search To find exceptional short-term rentals in the 18th Arrondissement of Paris with specific criteria:

{
  "market": {
    "country": "France",
    "region": "Ile-de-France",
    "locality": "Paris",
    "district": "18th Arrondissement"
  },
  "filter": {
    "superhost": {"eq": true},
    "rating_overall": {"gte": 4.9},
    "rating_cleanliness": {"gte": 4.95},
    "num_reviews": {"range": [50, 500]},
    "bedrooms": {"range": [1, 3]},
    "min_nights": {"lte": 3},
    "l90d_occupancy": {"gte": 0.75},
    "amenities": {"any": ["elevator", "air_conditioning"], "none": ["pets_allowed", "smoking_allowed"]}
  },
  "sort": {
    "rating_overall": "desc",
    "num_reviews": "desc",
    "l90d_revenue": "desc",
    "ttm_avg_rate": "asc"
  },
  "pagination": {
    "page_size": 10
  }
}

For Market Data

When querying for market data, the country, region, and locality fields are required. The district field is optional. Market analytics request bodies support filter, currency, and num_months. They do not support sort or pagination.

Locality-Level Market Search To analyze performance metrics for premium family-friendly listings in Paris:

{
  "market": {
    "country": "France",
    "region": "Ile-de-France",
    "locality": "Paris"
  },
  "filter": {
    "bedrooms": {"range": [2, 4]},
    "baths": {"gte": 1.5},
    "guests": {"range": [4, 8]},
    "amenities": {"all": ["kitchen", "washer", "wifi"], "any": ["crib", "high_chair", "childrens_books_and_toys"]},
    "ttm_revenue": {"gte": 50000},
    "rating_overall": {"gte": 4.7}
  },
  "num_months": 60,
  "currency": "usd"
}

District-Level Market Search To analyze luxury apartment performance in Manhattan's 10001 zip code:

{
  "market": {
    "country": "United States",
    "region": "New York",
    "locality": "New York",
    "district": "10001"
  },
  "filter": {
    "room_type": {"eq": "entire_home"},
    "bedrooms": {"gte": 2},
    "amenities": {"all": ["air_conditioning", "elevator", "wifi"], "any": ["pool", "gym", "sauna", "hot_tub"]},
    "ttm_avg_rate": {"gte": 400},
    "l90d_occupancy": {"range": [0.6, 0.95]},
    "cleaning_fee": {"lte": 300},
    "min_nights": {"range": [2, 7]}
  },
  "num_months": 24
}

Filterable Fields

Location

Field	Type	Operators
latitude	Numeric	eq, lt, lte, gt, gte, range
longitude	Numeric	eq, lt, lte, gt, gte, range
country	String	eq (Accepts 2-letter country code or full name)
region	String	eq
locality	String	eq
district	String	eq
exact_location	Boolean	eq

Property Details

Field	Type	Operators
amenities	List	any, all, none (can be combined on the same field)
baths	Numeric	eq, lt, lte, gt, gte, range
bedrooms	Numeric	eq, lt, lte, gt, gte, range
beds	Numeric	eq, lt, lte, gt, gte, range
guests	Numeric	eq, lt, lte, gt, gte, range
listing_id	Numeric	eq, lt, lte, gt, gte, range
listing_type	String	eq
min_nights	Numeric	eq, lt, lte, gt, gte, range
photos_count	Numeric	eq, lt, lte, gt, gte, range
room_type	String	eq
guest_favorite	Boolean	eq

Host

Field	Type	Operators
cohost_ids	List	any, all, none
cohost_names	List	any, all, none
host_id	Numeric	eq, lt, lte, gt, gte, range
host_name	String	eq
professional_management	Boolean	eq
superhost	Boolean	eq

Booking & Pricing

Field	Type	Operators
cleaning_fee	Numeric	eq, lt, lte, gt, gte, range
extra_guest_fee	Numeric	eq, lt, lte, gt, gte, range
instant_book	Boolean	eq
short_stay_cleaning_fee	Numeric	eq, lt, lte, gt, gte, range
single_fee_structure	Boolean	eq

Ratings

Field	Type	Operators
num_reviews	Numeric	eq, lt, lte, gt, gte, range
rating_accuracy	Numeric	eq, lt, lte, gt, gte, range
rating_checkin	Numeric	eq, lt, lte, gt, gte, range
rating_cleanliness	Numeric	eq, lt, lte, gt, gte, range
rating_communication	Numeric	eq, lt, lte, gt, gte, range
rating_location	Numeric	eq, lt, lte, gt, gte, range
rating_overall	Numeric	eq, lt, lte, gt, gte, range
rating_value	Numeric	eq, lt, lte, gt, gte, range

Performance Metrics (Last 90 Days)

Field	Type	Operators
l90d_adjusted_occupancy	Numeric	eq, lt, lte, gt, gte, range
l90d_adjusted_revpar	Numeric	eq, lt, lte, gt, gte, range
l90d_avg_rate	Numeric	eq, lt, lte, gt, gte, range
l90d_avg_min_nights	Numeric	eq, lt, lte, gt, gte, range
l90d_avg_length_of_stay	Numeric	eq, lt, lte, gt, gte, range
l90d_available_days	Numeric	eq, lt, lte, gt, gte, range
l90d_days_booked	Numeric	eq, lt, lte, gt, gte, range
l90d_occupancy	Numeric	eq, lt, lte, gt, gte, range
l90d_revenue	Numeric	eq, lt, lte, gt, gte, range
l90d_revpar	Numeric	eq, lt, lte, gt, gte, range

Performance Metrics (Trailing Twelve Months)

Field	Type	Operators
ttm_adjusted_occupancy	Numeric	eq, lt, lte, gt, gte, range
ttm_adjusted_revpar	Numeric	eq, lt, lte, gt, gte, range
ttm_avg_rate	Numeric	eq, lt, lte, gt, gte, range
ttm_avg_min_nights	Numeric	eq, lt, lte, gt, gte, range
ttm_avg_length_of_stay	Numeric	eq, lt, lte, gt, gte, range
ttm_available_days	Numeric	eq, lt, lte, gt, gte, range
ttm_days_booked	Numeric	eq, lt, lte, gt, gte, range
ttm_occupancy	Numeric	eq, lt, lte, gt, gte, range
ttm_revenue	Numeric	eq, lt, lte, gt, gte, range
ttm_revpar	Numeric	eq, lt, lte, gt, gte, range

Allowed Values

room_type

• entire_home
• private_room
• shared_room

amenities

• air_conditioning
• arcade_games
• baby_bath
• baby_monitor
• baby_safety_gates
• babysitter_recommendations
• backyard
• baking_sheet
• bar
• barbecue_utensils
• bathtub
• batting_cage
• bbq_grill
• beach_access
• beach_essentials
• bed_linens
• bidet
• bikes
• blender
• board_games
• boat_slip
• body_soap
• books_and_reading_material
• bowling_alley
• bread_maker
• breakfast
• building_staff
• cable_tv
• carbon_monoxide_alarm
• ceiling_fan
• changing_table
• childrens_bikes
• childrens_books_and_toys
• childrens_dinnerware
• childrens_playroom
• cleaning_before_checkout
• cleaning_products
• climbing_wall
• clothing_storage
• coffee
• coffee_maker
• conditioner
• cooking_basics
• crib
• dedicated_workspace
• dining_table
• dishes_and_silverware
• dishwasher
• doorman
• dryer
• drying_rack_for_clothing
• elevator
• essentials
• ethernet_connection
• ev_charger
• exercise_equipment
• exterior_security_cameras_on_property
• extra_pillows_and_blankets
• fire_extinguisher
• fire_pit
• fireplace_guards
• first_aid_kit
• free_parking_on_premises
• free_street_parking
• freezer
• game_console
• garden_view
• gated_property
• gym
• hair_dryer
• hammock
• hangers
• heating
• high_chair
• hockey_rink
• host_greets_you
• hot_tub
• hot_water
• hot_water_kettle
• indoor_fireplace
• iron
• kayak
• keypad
• kitchen
• lake_access
• laser_tag
• laundromat_nearby
• life_size_games
• lock_on_bedroom_door
• lockbox
• long_term_stays_allowed
• luggage_dropoff_allowed
• microwave
• mini_fridge
• mini_golf
• mosquito_net
• movie_theater
• noise_decibel_monitors_on_property
• ocean_view
• outdoor_dining_area
• outdoor_furniture
• outdoor_kitchen
• outdoor_playground
• outdoor_shower
• outlet_covers
• oven
• pack_n_play_travel_crib
• paid_parking_off_premises
• paid_parking_on_premises
• patio_or_balcony
• pets_allowed
• piano
• ping_pong_table
• pocket_wifi
• pool
• pool_table
• pool_view
• portable_fans
• private_entrance
• private_living_room
• record_player
• refrigerator
• resort_access
• rice_maker
• river_view
• room_darkening_shades
• safe
• sauna
• security_system
• self_check_in
• shampoo
• shower_gel
• single_level_home
• skate_ramp
• ski_in_ski_out
• smart_lock
• smoke_alarm
• smoking_allowed
• sound_system
• stove
• sun_loungers
• table_corner_guards
• theme_room
• toaster
• trash_compactor
• tv
• washer
• waterfront
• wifi
• window_guards
• wine_glasses

Sorting is supported on the /listings/search/* endpoints. Provide a sort object in the request body to order listing results. The sort object is a map of field names to sort directions (asc or desc). Order is preserved, with the first field having highest priority.

Example:

{
  "sort": {
    "ttm_revenue": "desc",
    "rating_overall": "desc",
    "num_reviews": "desc"
  }
}

Sortable Fields

Location

Field	Type
latitude	Numeric
longitude	Numeric

Property Details

Field	Type
baths	Numeric
bedrooms	Numeric
beds	Numeric
guests	Numeric
listing_id	Numeric
listing_type	String
min_nights	Numeric
photos_count	Numeric
room_type	String
guest_favorite	Boolean

Host

Field	Type
host_id	Numeric
host_name	String
professional_management	Boolean
superhost	Boolean

Booking & Pricing

Field	Type
cleaning_fee	Numeric
extra_guest_fee	Numeric
instant_book	Boolean
short_stay_cleaning_fee	Numeric

Ratings

Field	Type
num_reviews	Numeric
rating_accuracy	Numeric
rating_checkin	Numeric
rating_cleanliness	Numeric
rating_communication	Numeric
rating_location	Numeric
rating_overall	Numeric
rating_value	Numeric

Performance Metrics (Last 90 Days)

Field	Type
l90d_adjusted_occupancy	Numeric
l90d_adjusted_revpar	Numeric
l90d_avg_rate	Numeric
l90d_avg_min_nights	Numeric
l90d_avg_length_of_stay	Numeric
l90d_available_days	Numeric
l90d_days_booked	Numeric
l90d_occupancy	Numeric
l90d_revenue	Numeric
l90d_revpar	Numeric

Performance Metrics (Trailing Twelve Months)

Field	Type
ttm_adjusted_occupancy	Numeric
ttm_adjusted_revpar	Numeric
ttm_avg_rate	Numeric
ttm_avg_min_nights	Numeric
ttm_avg_length_of_stay	Numeric
ttm_available_days	Numeric
ttm_days_booked	Numeric
ttm_occupancy	Numeric
ttm_revenue	Numeric
ttm_revpar	Numeric

Pagination is controlled by the pagination object in the request body.

• /listings/search/* defaults to page_size: 10 and offset: 0
• /markets/summary and /markets/metrics/* do not use pagination; use num_months to control the time window for aggregated market analytics

Example:

{
  "pagination": {
    "page_size": 10,
    "offset": 20
  }
}

Access comprehensive Airbnb listings and vacation rental search capabilities through our property data API. Search and analyze short-term rental listing data across multiple markets to find investment opportunities and track competitor properties.