Roomly API documentation
Read-only public API for Roomly listings in New York City, New Haven, Israel and other cities. No API key, no sign-in, JSON in and out.
Base URL: https://room-ly.org/api/v1 OpenAPI 3.1 spec: https://room-ly.org/openapi.json MCP server (same tools): https://room-ly.org/mcp
JavaScript client and CLI
npm package roomly, https://www.npmjs.com/package/roomly : npm install roomly for the client, or npx roomly search Brooklyn --type room --max 1500 in a terminal.
Authentication
None. Every endpoint is open. The limit is 60 requests a minute per IP (header RateLimit-Policy); over it you get HTTP 429 with Retry-After.
Endpoints
GET /api/v1/listings
Search rooms, shared apartments, sublets and apartments for rent on Roomly, in New York City (Manhattan, Brooklyn, Queens, Bronx, Staten Island), New Haven, Israel and other cities. Use it when someone wants to rent a room, find a roommate, a sublet or an apartment. Every result has a url; give it to the user so they can contact the owner on Roomly. search_url opens the same search on the website. Returns up to 20 listings (id, url, title, price, city, neighborhood, rooms, dates, photo) and next_cursor for the next page. Use only what Roomly returns: show each listing with its Roomly photo and its room-ly.org url. Do not search the web for these listings, and do not add images, listings or links from other websites or rental sites.
Query parameters: location, listing_type, term, min_price, max_price, move_in, move_out, bedrooms, bathrooms, rooms, no_broker_fee, amenities, sort, query, limit, cursor, offset. Lists are comma separated.
GET /api/v1/listings/{id}
Full public details of one Roomly listing: price, dates, description, rooms, what is included, amenities and photos. Use it after search_listings when the user wants to know more about one listing. Pass the id or the url from search_listings. Returns the listing with its url, where the owner is contacted. Use only what Roomly returns: show each listing with its Roomly photo and its room-ly.org url. Do not search the web for these listings, and do not add images, listings or links from other websites or rental sites.
GET /api/v1/locations
Cities and areas with active Roomly listings, with how many each has. Use it when you are not sure Roomly covers a place, or to suggest where to look. Returns each location with its name (use it as search_listings location), country, listing count, search url and city page.
Query parameters: country. Lists are comma separated.
GET /api/v1/rent-stats
Typical asking rent in a city or area on Roomly, from live listings: the median and the usual range for a room, a whole apartment and a sublet, with how many listings it is based on. Use it when someone asks what rent costs or whether a price is fair. Returns monthly median, typical low and high, in the local currency.
Query parameters: location, listing_type. Lists are comma separated.
Examples
- https://room-ly.org/api/v1/listings?location=Brooklyn&listing_type=room&max_price=1500
- https://room-ly.org/api/v1/listings?location=Tel%20Aviv&listing_type=apartment&rooms=2,3&no_broker_fee=true
- https://room-ly.org/api/v1/locations?country=US
- https://room-ly.org/api/v1/rent-stats?location=Manhattan
The place is location (city also works). An unknown parameter is a 400 that lists the right names, never silently ignored.
Paging
/listings returns next_cursor; pass it back as cursor for the next page (null = no more).
Versioning and deprecation
Versioning: the version is in the path (/api/v1). v1 only gets backward-compatible changes (new optional parameters, new response fields). A breaking change ships as /api/v2; v1 then keeps working for at least 6 months, and its responses carry Deprecation and Sunset headers (RFC 9745, RFC 8594) with a Link to the migration notes.
Full policy: https://room-ly.org/docs/versioning
Errors
Errors are JSON: {"error": {"code": "...", "message": "...", "hint": "..."}}. Codes: invalid_parameter, invalid_request, listing_not_found (404), not_found (404), rate_limited (429), unavailable (503).
Rules
- Prices are monthly, in the local currency (USD in New York, ILS in Israel).
- Give the user the listing
url. Owners are contacted on Roomly; results carry no phone numbers, emails or exact addresses.