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

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/12345

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.

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 the power of 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"]},
    "amenities": {"any": ["pool", "hot_tub", "beach_access", "waterfront"]},
    "amenities": {"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": 25,
    "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": "US"
  },
  "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": 50,
    "offset": 0
  }
}

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

{
  "market": {
    "country": "US",
    "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"
}

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

{
  "market": {
    "country": "FR",
    "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"]},
    "amenities": {"none": ["pets_allowed", "smoking_allowed"]}
  },
  "sort": {
    "rating_overall": "desc",
    "num_reviews": "desc",
    "l90d_revenue": "desc",
    "ttm_avg_rate": "asc"
  },
  "pagination": {
    "page_size": 25
  }
}

For Market Data

When querying for market data, the country, region, and locality fields are required. The district field is optional.

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

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

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

{
  "market": {
    "country": "US",
    "region": "New York",
    "locality": "New York",
    "district": "10001"
  },
  "filter": {
    "room_type": {"eq": "entire_home"},
    "bedrooms": {"gte": 2},
    "amenities": {"any": ["pool", "gym", "sauna", "hot_tub"]},
    "amenities": {"all": ["air_conditioning", "elevator", "wifi"]},
    "ttm_avg_rate": {"gte": 400},
    "l90d_occupancy": {"range": [0.6, 0.95]},
    "cleaning_fee": {"lte": 300},
    "min_nights": {"range": [2, 7]}
  },
  "sort": {
    "ttm_revpar": "desc",
    "ttm_avg_rate": "desc",
    "l90d_occupancy": "desc",
    "rating_overall": "desc"
  },
  "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

Property Details

Field	Type	Operators
amenities	List	any, all, none
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

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

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_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_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
• 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
• 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
• 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
• gym
• hair_dryer
• hammock
• hangers
• heating
• high_chair
• hockey_rink
• hot_tub
• hot_water
• hot_water_kettle
• indoor_fireplace
• iron
• kayak
• kitchen
• lake_access
• laser_tag
• laundromat_nearby
• life_size_games
• lock_on_bedroom_door
• long_term_stays_allowed
• luggage_dropoff_allowed
• microwave
• mini_fridge
• mini_golf
• mosquito_net
• movie_theater
• 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
• portable_fans
• private_entrance
• record_player
• refrigerator
• resort_access
• rice_maker
• room_darkening_shades
• safe
• sauna
• shampoo
• shower_gel
• single_level_home
• skate_ramp
• ski_in_ski_out
• 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

You can sort your results by providing a sort object in the request body. 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. Only numeric fields are sortable.

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
min_nights	Numeric
photos_count	Numeric

Host

Field	Type
host_id	Numeric

Booking & Pricing

Field	Type
cleaning_fee	Numeric
extra_guest_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_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_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. You can specify the page_size and offset to retrieve a specific subset of the results. If pagination parameters are omitted, the API will use default values of page_size: 25 and offset: 0.

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.