API - Rentals Search

Introduction to Rentals Search API

Rentals Search API provides you with a programmatic way to search for rental listings within your account.   Please check with your local MLS association for rules when displaying MLS data.

Listings Request Syntax

To retrieve data using the Rentals Search API, you need to send a SECURE HTTP POST request to the follow URL: https://www.yougotlistings.com/api/rentals/search.php

You can use the following list of POST parameters to filter the listings returned from the API Server. Large result sets are generally slower to retrieve than smaller result sets. The maximum number of results returned in any request is 100. All parameters are case sensitive.
Name Required? Default Value Possible Values Purpose
key Required N/A Exactly as provided by YGL Authentication. Unauthorized requests are rejected.
avail_from Optional Null Valid date format in mm/dd/YY or mm/dd/YYYY If specified, only listings available starting on this date are returned.
avail_to Optional Null Valid date format in mm/dd/YY or mm/dd/YYYY If specified, only listings available up to this date are returned.
baths Optional Null Numbers separated by commas, Max Length 20 If specified, only listings with matching number of bathrooms are returned. e.g. "1,2" will return listings with 1 and 2 bathrooms.
beds Optional Null Numbers separated by commas, Max Length 20 If specified, only listings with matching number of bedrooms are returned. e.g. "1,2" will return listings with 1 and 2 bedrooms.
min_bed Optional Null Number If specified, only listings with greater bedrooms are returned.
max_bed Optional Null Number If specified, only listings with less bedrooms are returned.
city_neighborhood Optional Null Valid cities or neighborhoods separated by commas. Max Length 500. Neighborhood must be accompanied by the city it belongs to separated by ":". Ex. To search for brookline (city), Allston (neighborhood), Brighton (neighborhood), use "Brookline,Boston:Allston,Boston:Brigton" If specified, only listings with matching cities or neighborhoods are returned.
detail_level Optional 1 1 or 2 1 - Summary info only. Only 1 randomized photo is returned. No public title, description, features and poi. 2 - Full info, all fields are returned.
external_id Optional null Third party listing id. If specified, matching listing with external id will be returned.
include_off_market Optional 0 0 or 1 Indicates if pending and off market listings are included in search results. 0 will not include off market listing, 1 will include off market listings.
include_mls Optional 0 0 or 1 Indicates if MLS listings are included in search results. 0 will not include MLS listings, 1 will include MLS listings.
listing_id Optional Null A listing's ID If specified, the matching listing is returned if available. All other parameters are ignored. Full details are always returned.
listing_ids Optional Null Multiple listings' ID, separated by "," If specified, the matching listing is returned if available. All other parameters are ignored. Full details are always returned.
group_id Optional Null Int If specified, listings in the specified group are returned.
listing_fee Optional Null Fee paid by landlord. This will be returned as a percentage.  Example: 1 = 100%, .25 = 25%.  Special circumstances will also contain string such as "Negotiable" "Other".  MLS listings will return what is in MLS. If specified, only listings with the matching fee structure are returned. This field does not apply to MLS rental listings.
max_rent Optional Null Integer, Max Length 6 If specified, only listings with rent less than max_rent are returned.
min_rent Optional Null Integer, Max Length 6 If specified, only listings with rent greater than min_rent are returned.
page_count Optional Null Integer, Max Length 3 Specifies the number of listings returned per page. Can be used for paging when defined in conjunction with page_index. If used alone, it limits the total number of results returned.
page_index Optional Null Integer greater than 0, Max Length 3 Paging index, if specified only listings starting on that page are returned. Must be used in conjunction with page_count.
parking_spots Optional Null Integer If specified, only listings with the minimum number of parking spots returned.
pet Optional Null "cat", "dog", "friendly" "cat" - If specified, only listings accepting cat are returned. "dog" - If specified, only listings accepting dog are returned. "friendly" - If specified, only pet friendly listings (accepting both cat & dog) are returned.
photo Optional Null "Y" If specified, only listings with photos are returned.
POI Optional Null String separated by commas. Max 100 characters per POI. If specified, only listings with matching POI are returned.
sort_dir Optional Null "asc" or "desc" Sort the results in either ascending or descending order. Must be used in conjunction with "sort_field".
sort_name Optional Null Pre-defined values, Max Length 20 "availDate" - sort by (Available Date), "city" - sort by (City, Address, Street Number, Unit), "address" - sort by (Address, Street Number, Unit), "beds" - sort by (Bedrooms, Bathrooms), "baths" - sort by (Bathrooms, Bedrooms), "rent" - sort by (Rent), 'updateDate' - sort by (Last Update Date)
square_footage_max Optional Null Integer If specified, only listings with the maximum square footage are returned.
square_footage_min Optional Null Integer If specified, only listings with the minimum square footage are returned.
status_date Optional Null String in date format (mm/dd/YYYY) If specified, only listings that changed status after this date are returned. This is used to search for new / recently off market listings.
street_number Optional Null Max length 25 If specified, only listings with matching street number are returned.
street_name Optional Null Max length 100 If specified, only listings with matching street name are returned.
tags Optional Null String separated by commas. Max 100 characters per tag/feature. If specified, only listings with matching features or tags are returned.
video Optional Null "Y" If specified, only listings with videos are returned.
zip Optional Null Digits, Max Length 5 If specified, only listings with matching street zip code are returned.
Listings Response Syntax

Response from the Rentals Search API will be in XML format. Each response from the API includes a "responseCode" field. This is a number between 200 - 399, which indicates the response status of your request. A number between 200 - 299 indicates successful requests, and 300 - 399 indicates failure requests. Please see the response codes section below for a list of possible response codes and what each means. If a field is not available, the corresponding XML element will not be included in the response XML.

XML Response to a Successful Request
<YGLResponse responseCode="200">

   <SubTotal>100</SubTotal> -- Total listing results returned in the current response xml
   <Total>630</Total> -- Total number of listings matching the request criteria
   <PageIndex>1</PageIndex> -- Pass through parameter, returned as is from your request
   <PageCount>100</PageCount> -- Pass through parameter, returned as is from your request
   <SortName>rent</SortName> -- Pass through parameter, returned as is from your request
   <SortDir>asc</SortDir> -- Pass through parameter, returned as is from your request
   <DetailLevel>2</DetailLevel>  -- Indicates the response detail level based on request

   <Listings>
      <Listing>
         <Source /> -- "YGL" or "MLS"
         <ID />
         <ExternalID /> -- Third party primary id.
         <AgencyID /> -- The account ID this listing belongs to.  This field is available only if multiple agencies are associated to this key.
         <ListingAgentID />
         <StreetNumber />
         <StreetName />
         <City />
         <Neighborhood />
         <State />
         <Zip />
         <Unit /> -- NULL indicates there is no unit in the building.  * indicates there is unit number but unknown.
         <Latitude />
         <Longitude />
         <BuildingType /> -- (Apartment Complex, Condominium, Multi-Family, Single-Family, Townhouse, Brownstone)
         <Beds/>
         <BedInfo/> -- Contains additional info for the bed.  (#.8 = Split, 0.5 = Convertible)
         <Baths/>
         <TotalRooms/>
         <AvailableDate />  -- mm/dd/YYYY, NULL indicates the listing is always available. 
         <Price />
         <Fee />  -- Fee paid by landlord if any.  Can contain a decimal to represent a percentage, or string.  (MLS listings will be passed back as is.) 
         <Status />  -- Current on market status of this listing.  (ONMARKET, OFFMARKET, APP - app pending)
         <Pet />  -- (Dog Ok, Cat Ok, No Pet, Pet Friendly)
         <Student /> - (No Undergrad, No Student, Student Ok, Graduate Ok)
         <SquareFootage />
         <UnitLevel />
         <HeatSource/>
         <Parking /> -- Available, Garage, Included, Street
         <IncludeElectricity/> -- Does rent include electricity (0, 1)
         <IncludeGas/> -- Does rent include gas (0, 1)
         <IncludeHeat/> -- Does rent include heat (0, 1)
         <IncludeHotWater/> -- Does rent include hot water (0, 1)
         <Title />
         <BuildingDescription />
         <UnitDescription />
         <MlsAgentName /> -- The listing agent in MLS
         <MlsOfficeName /> -- The listing office in MLS
         <POI>  
            <Point />
            ...
         </POI>
         <Features> 
            <Feature />
            ...
         </Features>
         <Tags> -- IMPORTANT:  Listing tags are private information, they CANNOT be displayed on external website.   
            <Tag />
            ...
         </Tags>
         <Photos>  
            <Photo>http://www.yougotlistings.com/photos/123.jpg</Photo>  
            ...
         </Photos>
         <Videos>
            <Video>http://www.youtube.com/...</Video> - Url to the youtube video
         </Videos>
         <MoveInCosts> - Only if include_move_in_costs is 1
            <IsFirstMonthRequired>1</IsFirstMonthRequired>
            <IsLastMonthRequired>1</IsLastMonthRequired>
            <PetDeposit>100</PetDeposit>
            <Fee>1000</Fee>
            <KeyDeposit></KeyDeposit>
            <SecurityDeposit>100</SecurityDeposit>
            <ApplicationFee>100</ApplicationFee>
         </MoveInCosts>
      <Listing>
      ...
   </Listings>

</YGLResponse>
XML Response to a Failed Request
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<YGLResponse responseCode="300">

   <Error>Listing retrieving failed.</Error>

</YGLResponse>
Response Codes

The response codes are current work in progress. Please check back periodically to see if new ones are added.
Code Reason
200 Successful request.
201 Successful request, but no matching results are found.
300 Failed request. Reason Unknown.
301 Invalid request parameter.

Feedback and Knowledge Base