"Listings" Method

"Listings" Method

The "listings" method is the primary way to fetch Oodle listings from our REST API.

The "listings" endpoint URL is: 

https://api.oodle.com/api/v2/listings

Sample URL

To specify your Oodle listings request, simply add query string parameters to the end of the "listings" endpoint URL, for example: 
https://api.oodle.com/api/v2/listings?key=TEST&region=chicago&category=vehicle/car

Sample Response

Click here to see the response for the sample URL above. By default, the Oodle REST API returns listings data in plain XML. Other output format options are documented below.

URL Encoding

Spaces should be URL encoded to "%20". Commas should be URL encoded to "%2C".

For example, if you want to do a keyword search for "software engineer", you would encode that as "software%20engineer": 

https://api.oodle.com/api/v2/listings?key=TEST&region=sf&category=job&q=software%20engineer
The same is true for locations. Here is an example for "San Mateo, CA": 
https://api.oodle.com/api/v2/listings?key=TEST&region=usa&category=job&location=San%20Mateo%2C%20CA

API Parameters

key
Required. The API key assigned to you by Oodle. It must be included with every request.
region
Required. A region can be a metro area or an entire country. Each Oodle region has a unique string.

Possible values:
See the current list on the Regions List page.

For hints on how to set region/location, see the "Region vs. Location" section below.

q
Optional. The query, or list of keywords, that must be present. A limited amount of stemming is applied. Additionally:
  • The "+" modifier is accepted, but ignored.
  • The "-" or "NOT" operator is used to require that the modified keyword does not appear.
  • The "OR" operator allows a logical OR between keywords.
  • Parantheses can be used for grouping terms.
  • The double-quote character can be used for phrase matching.
category
Optional. The category argument is a string representing the category code. The given category and all sub-categories will be searched. Using the empty string represents the root, and all sub-categories will be searched.

Possible values:
See the current list on the Categories List page.

attributes
Optional. This parameter is used to refine your query in the same that you would on the Oodle web site using the navigators in the left rail. For example: color, make, model, bedrooms, bathrooms, etc.

You can define many attributes on a request. Simply build a comma-delimited list of all of the attributes you wish to query. Here's an example.

Let's say you want to query for Honda Civics, priced between $12000 and $15000, with less than 60000 miles.

The attribute values for this query would be: 

make_honda
model_civic
price_12000_15000
mileage_60000-
Assemble your attribute list in this way: 
&attributes=make_honda,model_civic,price_12000_15000,mileage_60000-

Possible values:
See the full list of attributes on the Attributes List page.

location
Optional. Limits results to a specific location. Free-form text for a location causes a search through our location database. Value can be in any of the following formats:
  • zip code / postal code
    &location=90210
  • city, state (e.g. Palo Alto, CA)
    &location=Palo%20Alto%2C%20CA
  • city name only (e.g. Chicago)
    &location=Chicago
  • Oodle city code (e.g. usa:ca:paloalto)
    &location=usa:ca:paloalto
  • lat/lon centerpoint (e.g. 41.9,-87.6)
    &location=41.9%2C-87.6
  • lat/lon box - SW Lat, SW Lon, NE Lat, NE Lon (e.g. 33.9,-118.4,36.1,-115.2)
    &location=33.9%2C-118.4%2C36.1%2C-115.2
Tip: If you're setting a "location" value, just set the "region" to be a nation-wide value (e.g. "region=usa&location=90210").

For more info, see the "Region vs. Location" section below.

radius
Optional. Distance (in miles) from the specified location for which results should be returned. Default is 30. Setting a radius of 0 will result in listings being returned ONLY from your specific location.
mappable
Optional. Filters listings based on how 'mappable' they are.

Set this to address to only return listings that have a full, exact street address, for example: 

&mappable=address
If 'address' is used, as in the example above, the latitude/longitude for each listing in the response will represent the precise location for the listing. This is helpful for maps mashups and other mapping applications.

If this parameter is not set (the default case), the response will include listings with various levels of location preciseness - some listings may have zip code only, some may have a city only, and some will have the full, exact address.

Pro tip: If you're using this parameter, choose your 'category' wisely. Certain categories have much better 'mappable' coverage than others. For example, many listings in 'housing/rent' and 'housing/sale' have an exact address, as you'd imagine. Other categories such as 'personals', however, have very few listings with an exact street address. In that latter case, using this parameter will greatly limit your result set.

start
Optional. Declares the start index of the result set. Default is 1. Numbering starts at "1".
num
Optional. Declares the number of results to return. Default is 10. Maximum is 50.
sort
Optional. Describes how the result listings should be sorted.

Possible values:

  • ctime - by listing's creation time - oldest to newest
  • ctime_reverse - by listing's creation time, reverse order - newest to oldest
  • distance - by distance from "location" value above - closest to farthest
  • distance_reverse - by distance from "location" parameter, reverse order - farthest to closest
  • eventdate - by date of event (e.g. tickets listings) - in chronological order
  • eventdate_reverse - by date of event - in reverse chronological order
  • price - by listing's price - lowest to highest
  • price_reverse - by listing's price, reverse order - highest to lowest

refinements
Optional. Declares whether to return the navigational refinements.

Possible values:

  • none - do not return navigational refinements
  • simple - only return simple navigational refinements, e.g. category refinements
  • full - return full navigational refinements

ctime_low
Optional. Lower bounds of listing "creation time" filter. Value is in Unix epoch seconds.
ctime_high
Optional. Upper bounds of listing "creation time" filter. Value is in Unix epoch seconds.
exclude_sources
Optional. A comma-delimited list of Oodle source IDs that should be excluded from the results.
paid    (NEW!)
Optional. Performs some filtering to return paid/featured/sponsored listings only. Please note: This may limit your result set quite a bit. Specifically, there will be fewer user-posted ads among the result set. If you're interested in using this parameter, please test it across a variety of queries and make sure that the results you receive make sense for your application.

Possible values:

  • yes - return paid listings only

assisted_search
Optional. If you have many Oodle API requests with a keyword query term ("q"), but no category, you may wish to set assisted_search to yes. If set to yes, Oodle performs some additional processing on the query term to attempt to automatically determine the category for you.

In this case, the relevance of the results will likely improve, but you may notice slightly longer response times from the Oodle API as we perform that processing.

Possible values:

  • yes - perform assisted search operation

format
Optional. Output format of results. Default is XML.

Possible values:

  • xml - output is formatted in plain old XML
  • json - output is fromatted in JSON (JavaScript Object Notation)
  • php_serial - output structure formatted in serialized PHP
  • php_export - output structure formatted as valid PHP
  • dump - output is dumped with no formatting
  • rss2 - listing information returned in RSS 2.0 format
Please note that with the "rss2" format option, only a limited amount of information is returned -- for each listing, the title, price, description, and thumbnail image are available. Navigational refinements and other information are not returned for rss2.

jsoncallback
By default, format=json wraps the JSON response as such:
jsonOodleApi({...})

You may, however, change this behavior through the use of the "jsoncallback" parameter.

Specifically, you can tell us to remove this wrapper entirely or you may specify one of your own.

Possible values:

  • none - no json callback will be applied - JSON output: {...}
  • foo - "foo" is used as wrapper - JSON output: foo({...})


Images

Listings in the Oodle index often have multiple photos. This section will provide you with an overview of the information we return for each of those images.

In order to make life easier for you, the API developer, we take every listing photo and resize it into several different sizes:

  • s - small - 100x75
  • m - medium - 144x108
  • l - large - 208x156
  • x - x-large - up to 400x300
Let's walk through how that looks by using an example of a listing for a home for sale. It's easy to imagine that such a real estate listing would have these photos:
  • Kitchen photo
  • Living room photo
  • Dining room photo
Remember, listings don't always have photos. But when they do, the images we provide will be in the sizes above.

So, using the "house for sale" example above, our API response would include information for all of these images:

  • Kitchen photo - s, m, l, x
  • Living room photo - s, m, l, x
  • Dining room photo - s, m, l, x
So far, so good! Each photo can come back in many sizes.

Now, for each of those sized images (for example, the "s" kitchen photo), we give you:

  • src - the full path of the image
  • width - the pixel width of the image
  • height - the pixel height of the image
  • alt - a title/caption for the image, ready to be used in the IMG's 'alt' HTML attribute
  • num - the order of this image in the overall set (e.g. kitchen photo = 0, living room photo = 1, dining room photo = 2, etc.)
  • size - the size of the image ("s", "m", "l", or "x")
Here is a sample piece of our API response in XML format showing this: 
<element>
 <src>https://i.oodleimg.com/item/2150075350u_0m_single-family_houses_in_san_f...</src>
 <width>144</width>
 <height>108</height>
 <alt>Famous Forest Hills Home</alt>
 <num>0</num>
 <size>s</size>
</element>
So in the example above, you've got a total of 12 images (3 photos * 4 different sizes) being returned, and for each of those 12 images, we're returning several pieces of data (size, width, height, etc.).

By default, all of this information is returned for all of the images on a listing. You can see that this adds up pretty quickly and the API response can get very large. If you need all of these images, the data we provide is rich and helpful. But, what if you don't need all of that information?

That is, what if you're displaying a set of search results and you simply need the first image? Or you only need images of a particular size (e.g. the 100x75 images, but not the other sizes)?

In that scenario, you'd be downloading a lot of extra image data, which would unnecessarily slow down your API call.

Fortunately, we now provide some API parameters to you so that you can control both how many images you get back and also which sizes you'd like. This next section covers those parameters.

Image Parameters

num_images
Optional. By default, all images are returned for each listing. You may, however, change this behavior through the use of the "num_images" parameter.

Example:

  • &num_images=0 - images will never be returned, even if listings have them
  • &num_images=1 - each of the sizes (s, m, l, etc.) will be returned for the first listing photo
  • &num_images=2 - each of the sizes (s, m, l, etc.) will be returned for the first two listing photos

image_sizes
Optional. By default, all images sizes are returned for each photo. You may, however, change this behavior through the use of the "image_sizes" parameter. Specify the sizes you'd like returned to you. Possible values are "s", "m", "l", and "x". You may specify multiple values by using a comma-separated list.

Example:

  • &image_sizes=s - only return the "s" (small) images
  • &image_sizes=m - only return the "m" (medium) images
  • &image_sizes=m,l - only return the "m" (medium) and "l" (large) images

Tip: Use both of the parameters above ("num_images" and "image_sizes") to really filter down the image information you receive in the API response.

For example, if the only image you want for each listing is the "s" sized thumbnail of the first listing photo, you could accomplish that with: 

&num_images=1&image_sizes=s

"Region" vs. "Location"

If you simply want listings from a broad metro area (e.g. SF Bay Area):
  • Set “region” to the metro area you want (region=sf)
  • Leave “location” parameter off entirely
If you want listings from a specific city/state, zip, lat/long (e.g. Palo Alto, CA):
  • Set “region” to the country level (region=usa)
  • Set “location” to that specific location (location=Palo%20Alto%2C%20CA)
Recall that if you set a "location", the default search radius around that location is 30 miles. Set the radius parameter to change this.