2 requests per second included with Team Account.  Bandwidth can be increased to 20 requests per second for an additional $100 / mo.

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

The API cannot be accessed from the front end browser directly. It needs to be accessed from a backend server.

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.
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.
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.
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.
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.
min_rent	Optional	Null	Integer, Max Length 6	If specified, only listings with rent greater than min_rent are returned.
max_rent	Optional	Null	Integer, Max Length 6	If specified, only listings with rent less than max_rent are returned.
listing_fee	Optional	Null	Fee paid by landlord. Example: 1 = 100% of one month, .50 = 50% of one month, 0=No Fee Paid. Special circumstances will also contain strings such as Boat=Boat, Negotiable= Negotiable, Other=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 listings.
photo	Optional	Null	"Y"	If specified, only listings with photos are 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.
parking	Optional	Null	"Y"	If specified, only listings with parking are returned.
square_footage_min	Optional	Null	Integer	If specified, only listings with the minimum square footage are returned.
square_footage_max	Optional	Null	Integer	If specified, only listings with the maximum square footage are returned.
features	Optional	Null	String separated by commas. Max 100 characters per tag.	If specified, listings with matching features are returned.
tags	Optional	Null	String separated by commas. Max 100 characters per tag.	If specified, listings with matching tags are returned.  Listings that belong to landlords with matching tags are also returned.
tours	Optional	Null	"Y"	If specified, only listings with videos/virtual tours are returned.
detail_level	Optional	1	1 or 2	1 - Summary info only with 1 photo returned. No public title, description, features and POI. 2 - Full info, all fields are returned.
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.
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.  If left blank, the aggregated cities in all user's Default Cities list will be selected.
zip	Optional	Null	Digits, Max Length 5	If specified, only listings with matching street zip code are returned.
external_id	Optional	Null	Third party listing id.	If specified, matching listing with external id will be returned.
listing_id	Optional	Null	A listing's ID	If specified, matching listing is returned. All other parameters are ignored. Full details are always returned.
listing_ids	Optional	Null	Multiple listings' ID, separated by ","	If specified, matching listings are returned. All other parameters are ignored. Full details are always returned.
exclude_listing_ids	Optional	Null	Multiple listings' ID, separated by ","	If specified, matching listings are excluded from returned results.
group_id	Optional	Null	Int	If specified, listings in the specified Rental Group are returned.
listing_agent_id	Optional	Null	Int	If specified, listings with the specified listing agent are returned.
include_internal	Optional	1	0 or 1	Refers to listings entered in manually by the client. 0 will not include Internal listings, 1 will include Internal listings.
include_data_entry	Optional	1	0 or 1	Refers to listings updated by YGL. 0 will not include Data Entry listings, 1 will include Data Entry listings.
include_ygl_network	Optional	1	0 or 1	Refers to listings shared by landlords directly. 0 will not include Network listings, 1 will include Network listings.
include_mls	Optional	1	0 or 1	Refers to listings from MLS. 0 will not include MLS listings, 1 will include MLS listings.
include_landlord_info	Optional	1	0 or 1	Only available to clients with Advanced API access. If set to 1, landlords info are included in the results. See sample results below for landlords format info.
page_count	Optional	Null	Integer, Max Length 3, Max Value 100	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	If specified only listings starting on that page are returned. Must be used in conjunction with page_count.
sort_dir	Optional	Null	"asc" or "desc"	Sort the results in either ascending or descending order. Must be used in conjunction with "sort_name".
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)
latitude_start	Optional	Null	Valid geo coordinate	If provided only listings within the specified Geo area are returned. All 4 coordinate fields are required for this to work.
latitude_end	Optional	Null	Valid geo coordinate	If provided only listings within the specified Geo area are returned. All 4 coordinate fields are required for this to work.
longitude_start	Optional	Null	Valid geo coordinate	If provided only listings within the specified Geo area are returned. All 4 coordinate fields are required for this to work.
longitude_end	Optional	Null	Valid geo coordinate	If provided only listings within the specified Geo area are returned. All 4 coordinate fields are required for this to work.
last_updated_date	Optional	Null	Valid date (mm/dd/yyyy)	If provided only listings updated since the specified date is returned.
request_type	Optional	XML	JSON or XML	If provided results will be returned in the specified format.  JSON is preferred with more detailed information.

unitFeatures - Contains unit specific features.
buildingFeatures - Contains building specific features.  
unitPhotos - Contains unit photo URL, thumbnail, display order and other extra info.
buildingPhotos - Contains building photo url, thumbnail, display order and other extra info.
moveInCosts - Non-MLS listings contain total_move_in_costs, mic_first_month, mic_last_month, mic_security, mic_application_fee, mic_move_in_fee, mic_pet_deposit, mic_key_deposit. MLSPIN listings contain First Month, Last Month, Security fields. (Only available to clients with Advanced API access.)

Listings Response Syntax

Response from the Rentals Search API will be in XML or JSON 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>1000</Total> -- Total number of listings matching the request criteria
   <PageIndex>1</PageIndex> -- Pass through parameter, returned as is from your request
   <PageCount>10</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/>
         <BedsName/> -- 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 />
         <Laundry />  -- (Washer/Dryer in Unit, Laundry in Building, Laundry on Site, Washer/Dryer Hookups, None, Unknown)
         <HeatSource/>
         <Parking > -- Available for non-MLS listings.
            <ParkingAvailability />  -- AVL=Available, FOR=For Rent, INC=Included, NON=None
            <ParkingType /> -- Covered, Outdoor, Garage, Tandem, Permit, Valet, Street
            <ParkingNumber />
            <ParkingPrice />
         </ Parking> 
         <MlsParking > -- Only for MLS listings.
            <Total /> 
            <Garage />
            <Carport />
            ...
         </ Parking> 
         <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
         <MlsFeatures> -- Only available for MLS listings.
            <MlsFeature>
               <Name />
               <Feature />
            </MlsFeature>
            ...
         </Features>
         <Features>  -- Available for non-MLS listings.
            <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>
         <Photos360>  
            <Photo>
               <URL>http://www.yougotlistings.com/photos/123.jpg</URL>
               <Caption>Test Caption</Caption>
            </Photo>  
            ...
         </Photos360>
         <Videos>
            <Video>http://www.youtube.com/...</Video> -- Url to the youtube video.
         </Videos>
      <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.

Sample Code

$ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://www.yougotlistings.com/api/rentals/search.php");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  $fields = [
     "key" => urlencode("PUT_YOUR_KEY_HERE")
  ];

  $fields_string = "";

  foreach ($fields as $key => $value) { 
     $fields_string .= $key.'='.$value.'&'; 
  }

  $fields_string = rtrim($fields_string, '&');

  curl_setopt($ch,CURLOPT_POST, count($fields));
  curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);

  $body = curl_exec($ch);
  $info = curl_getinfo($ch);
  curl_close($ch);

  if ($info["http_code"] != 200 && $info["http_code"] != 302) {
     // Handle Error
     return;
  }

  print_r($body);