get

The get method is the primary way to fetch listings from the Oodle API.

Input Parameters

The method takes one parameter -- a hash containing multiple keys:

partner_id

String. Required. This is the API key that was assigned to you by Oodle. It must be included with every request.

region

String. Required. A region is a metro area or an entire country. Each Oodle region has a unique string. See the current list on the Regions List page.

q

String. 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.

from

Integer. Optional. Declares the start index of the result set. 0-based index.

to

Integer. Optional. Declares the end index of the result set. 0-based index.

category

String. Optional. The category argument is a string representing the category code. The given category and all sub-categories will be searched. See the current list on the Categories List page. Using the empty string represents the root, and all sub-categories will be searched.

dimensions

Array of strings. 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: by color, make, model, whether the listing has a thumbnail or not, etc. See the current list on the Dimensions List page. Note that "dimensions" are passed back to you in the "refinements" block of every response. This allows you to easily offer a multi-step search refinement experience, similar to the Oodle web site, if you so desire.

filters

Array of structs. Optional. Another way to filter the results on your query. Each filter is a struct:

• type - a string representing a filter, e.g. 'price'
• params - an array of parameters for that type, e.g. 'low', 'high'

Possible values for 'type' are:

• create_time
• distance
• price
• source
• boundingbox

Possible values for 'params' will vary by filter type. Note that "filters" is an array of individual filter structs - this means that you can have multiple filters on each query. See examples below for more information.

sort

Struct. Optional. Describes how the result listings should be sorted. A sort is a struct:

• key - one of the strings from the list above, e.g. 'distance'
• reverse - an optional boolean, can be added to reverse the sort order, e.g. TRUE

Possible 'key' values include:

• distance
• normal
• price
• create_time
• eventdate

location

Struct. Optional. Free-form text for a location causing a search through our location database. Alternately, a location ID (e.g. 'usa_tx_austin') may be passed in if that is known.

return_nav

Boolean. Optional. Declares whether to return the navigational refinements. (See "Refinements" below.)

assisted_search

Boolean. Optional. If you have many Oodle API requests with a keyword query term, but no category, you may wish to set assisted_search to TRUE. If set to TRUE, 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. Default is FALSE.

Input Parameters - Some Examples

"dimensions"

An array of dimension values is passed in as such:

[
    'make_ford',
    'model_explorer',
    'has_photo_thumbnail',
    'color_blue'
]

"filters"

create_time - Listings added to our system during a certain time period. Times are in epoch seconds.

{
    type   => 'create_time',
    params => { 
        low  => 1156453260, 
        high => 1156453200 
    }
}

distance - Within a given distance of a zip code.

{ 
    type   => 'distance', 
    params => { 
        value        => 30, 
        units        => 'mi', 
        zip          => '94105',
        country_code => 'USA'   # optional - will default to USA
    }
}

distance - Within a given distance of a postal code in UK

{ 
    type   => 'distance', 
    params => { 
        value        => 15, 
        units        => 'km', 
        zip          => 'L69 7ZP',
        country_code => 'GBR'
    }
}

distance - Within a given distance of a lat/long pair.

{ 
    type   => 'distance', 
    params => { 
        value     => 100, 
        units     => 'mi', 
        latitude  => 46.6072, 
        longitude => -120.621
    }
}

price - Listings within a certain price range.

{
    type   => 'price',
    params => { 
        low  => 10, 
        high => 30 
    } 
}

source - Exclude listings from particular source(s), e.g. ebay and backpage:

{
    type   => 'source',
    params => { 
        exclude => [ 'ebay', 'backpage' ] 
    } 
}

boundingbox - Include listings within a particular lat/lon rectangle. The four parameters are [SW Lat, SW Lon, NE Lat, NE Lon].

{
    type => 'boundingbox',
    params => {
        swLat => 30.949,
        swLon => -99.842,
        neLat => 34.641,
        neLon => -93.746
    }
}

"location"

Pass in country code + free form text:

{ 
    country_code => 'USA',
    text         => 'Austin' # this is the user's free-form text
}

In the UK, the country_code will be "GBR":

{ 
    country_code => 'GBR',
    text         => 'London' 
}

Or, when the location id is known, this is preferred:

{ 
    id => 'usa_tx_austin'
}

"sort"

price - Sort listings by price, lowest to highest.

{
    key => 'price'
}

price using "reverse" - Sort listings by price, highest to lowest.

{
    key => 'price',
    reverse => true
}

distance - Sort listings by distance away from the location, nearest ones first.

{
    key => 'distance'
}

distance using "reverse" - Sort listings by distance from the location, nearest ones last.

{
    key => 'distance',
    reverse => true
}

Response

The response on the "get" request will be a hash structure containing up to 5 top level items:

Here is the full response data structure:

{
    /***********************
     * "total"
     * The total number of listings Oodle has for your query.
     ***********************/
    'total' => (string),

    /***********************
     * "items"
     * Array of Oodle listings.  Note that the structure of each
     * item will vary slightly depending on the category of the item.  For example, 
     * "Make" and "Model" appear in vehicles listings, but not in job listings
     ***********************/
    'items' => (array of hashes)
    [
        {
            'title' => (string),          # listing title
            'sbody' => (string),          # full listing body (if available)
            'body' => (string),           # short listing body snippet (if available) 
            'source' => (string),         # name of site where full listing is located
            'category_name' => (string),  # category name (e.g. 'Cars & Vehicles')
            'category_attr' => (string),  # location in Oodle category tree (e.g. 'vehicle/car')
            'id' => (string),             # Oodle listing ID number
            'url' => (string),            # Oodle listing click URL
            'create_time' => (string),    # listing creation time (epoch seconds)
            'paid' => (boolean),          # see "Paid Listings" section below
            'revenue_score' => (string),  # see "Paid Listings" section below
            # THERE ARE *MANY* OTHER OPTIONAL FIELDS THAT MAY SHOW UP, INCLUDING:
            'price' => (string),          # price of item
            'registration' => (string),   # is registration required at source site?
            'thumb' => (string),          # thumbnail image URL
            'image_width' => (string),    # width of thumbnail image (in pixels)
            'image_height' => (string),   # height of thumbnail image (in pixels)
            'color' => (string),          # color of item
            'year' => (string),           # year of item
            'latitude' => (string),       # decimal latitude of item (e.g. 37.5382996)
            'longitude' => (string),      # decimal longitude of item (e.g. -122.3039017)
            'zipcode' => (string),        # postal code for location of item
            'location' => (string),       # general descriptive name for location of item
            'locationcity' => (string),   # city name for location of item
            'privateparty' => (string)    # item sold by private party individual?
        }
    ],

    /***********************
     * "current"
     * This will only exist if your query is more than a simple keyword + region.
     * Note that this structure will change depending on your incoming query.  
     * For example, if you didn't set any dimensions on your incoming query, that won't be here.
     * Here is an example for a Honda vehicles API query near Los Angeles, CA: 
     ***********************/
    'current' => (hash)
    {
        'category' => (array of hashes)
        [
            {
                'name' => (string),      # category full name (e.g. "Cars")
                'abbrev' => (string),    # category short name (e.g. "Cars")
                'id' => (string),        # category id (e.g. "vehicle")
                'url' => (string)        # Oodle url path for category (e.g. "vehicle")
            },
            {
                'name' => (string),      # category full name (e.g. "Cars & Vehicles)
                'abbrev' => (string),    # category short name (e.g. "Cars")
                'id' => (string),        # category id (e.g. "vehicle/car") 
                'url' => (string)        # Oodle url path for category (e.g. "vehicle/car")
            }
        ],
        'dimension' => (array of hashes)
        [
            {
                'name' => (string),      # dimension name (e.g. "Make")
                'value' => (string),     # dimension value (e.g. "Honda")
                'id' => (string)         # dimension id (e.g. "make_honda")
            }
        ],
        'filter' => (array of hashes)
        [
            { 
                'type' => (string),      # (e.g. "distance")
                'params' => (hash)
                { 
                    value => (string),   # (e.g. "30")
                    units => (string),   # (e.g. "mi") 
                    zip   => (string)    # (e.g. "90210")
                }
            },
            {
                'type' => (string),      # (e.g. "price")
                'params' => (hash)
                { 
                    'low'  => (string),  # (e.g. "15000")
                    'high' => (string)   # (e.g. "25000")
                }
            }
        ],
        'location' => (hash)
        {
            'name'  => (string),  # location name (e.g. "Los Angeles")
            'state' => (string),  # location state name (e.g. "CA")
            'id'    => (string)   # Oodle location ID (e.g. "usa_ca_losangeles")
        }
    },

    /***********************
     * "refinements"
     * The refinements structure **will change** depending on your incoming query.
     * Here is an example refinement set for the vehicles API query we just used above. 
     ***********************/
    'refinements' => (hash)
    {
        'category' => (array of hashes)
        [
            {
                'name' => (string),  # refinement category name (e.g. "Cars")
                'id' => (string),    # refinement category id (e.g. "vehicle")
                'count' => (string)  # num of listings in suggested refinement (e.g. "6612")
            }
        ],
        'dimension' => (array of hashes)
        [
            {
                'name' => (string),   # dimension refinement name (e.g. "Make")
                'values' => (array of hashes)
                [
                    {
                        'name' => (string),  # refinement dimension value (e.g. "Toyota")
                        'id' => (string),    # refinement dimension id (e.g. "make_toyota") 
                        'count' => (string)  # num of listings in suggested refinement (e.g. 9745)
                    }
                ]
            }
        ]
    },

    /***********************
     * "suggestions"
     * If you submitted a common city name (one that exists in many states), you 
     * will likely receive this "suggestions" hash which will provide you with a 
     * full list of complete location suggestions.  Here's an example below for 
     * location: "Austin", Region: "usa", a city name found in many states.
     ***********************/      
    'suggestions' => (hash)
    {
        'location' => (array of hashes)
        [
            {
                'name'  => (string),  # location city name (e.g. "Austin")
                'state' => (string),  # location state abbreviation (e.g. "MN")
                'id'    => (string)   # Oodle location ID (e.g. "usa_mn_austin")
            },
            {
                'name'  => (string),  # location city name (e.g. "Austin")
                'state' => (string),  # location state abbreviation (e.g. "TX")
                'id'    => (string)   # Oodle location ID (e.g. "usa_tx_austin")
            }
        ]
    }
}

Paid Listings

On Oodle.com, you'll sometimes see listings that are marked as "Featured" (see screenshot above). These are listings that have received a boost within the search results because they are part of our Paid Inclusion Program.

We also specify which listings are "paid" within our API response. Clicks on these listings can generate revenue for you if you are part of our API Affiliate Program.

Specifically, on each item within the API response, you'll see two values of interest: