"Listings" Method

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

The "listings" endpoint URL is: 

http://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: 
http://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": 

http://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": 
http://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 (e.g. 90210)
  • city, state (e.g. Palo Alto, CA)
  • city name only (e.g. Chicago)
  • Oodle city code (e.g. usa:ca:paloalto)
  • lat/lon centerpoint (e.g. 41.9,-87.6)
  • lat/lon box (e.g. 33.9,-118.4,36.1,-115.2) - SW Lat, SW Lon, NE Lat, NE Lon
For hints on how to set region/location, 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.
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.
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({...})


"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,%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.