LemonFree API 2.0 Documentation - Listings Feed

Last Updated: January 21, 2014

Overview

The Listings feed provides access to all vehicle listings on LemonFree.

Base URL

http://api.lemonfree.com/v2/listings

Parameters

Parameter Type Occurrence Description
key string required Your API key
format Result Format optional Sets the format of the result.
If format is not specified the default format is xml.
make | make_id string | int optional A specific make (or ID) that has been obtained by the makes feed.
If used:
  bodystyle must not be specified

Only make or make_id must be set. If both are specified an error will be returned.
model | model_id string | int optional A specific model (or ID) that has been obtained by the models feed.
If used:
  make (or make_id) must also be specified
  bodystyle must not be specified

Only model or model_id must be set. If both are specified an error will be returned.
trim | trim_id string | int optional A specific trim (or ID) that has been obtained by the trims feed.
If used:
  make (or make_id) must also be specified
  model (or model_id) must also be specified
  bodystyle must not be specified

Only trim or trim_id must be set. If both are specified an error will be returned.
bodystyle Bodystyle optional limits the results to the specified body style
If used:
  make (or make_id), model (or model_id), and trim (or trim_id) must not be   specified
zip string optional limits the results to a particular location as defined by a zip/postal code. An area can be specified by including the distance parameter.
If used:
  distance must be specified
  city, state, and country must not be specified
distance Distance optional limits the results to an area around the provided zip/postal code
If used:
  zip must be specified
  city, state, and country must not be specified
city string optional limits the results to the specified city
If used:
  state must be specified
  zip, distance, and country must not be specified
state State optional limits the results to the specified state or province
If used:
  zip, distance, and country must not be specified
country Country optional limits the results to the specified country
If used:
  zip, distance, city, and state must not be specified
price_min Price optional Limits the results to a price range; price_min specifies the lower end of this range.
If used, price_max must also be specified, and be greater than or equal to price_min.
price_max Price optional Limits the results to a price range; price_max specifies the upper end of this range.
If used, price_min must also be specified, and be less than or equal to price_max.
mileage_min Mileage optional Limits the results to a mileage range; mileage_min specifies the lower end of this range.
If used, mileage_max must also be specified, and be greater than or equal to mileage_min.
mileage_max Mileage optional Limits the results to a mileage range; mileage_max specifies the upper end of this range.
If used, mileage_min must also be specified, and be less than or equal to mileage_max.
year_from Year optional Limits the results to a year range; year_from specifies the lower end of this range.
If used, year_to must also be specified, and be greater than or equal to year_from.
year_to Year optional Limits the results to a year range; year_to specifies the upper end of this range.
If used, year_from must also be specified, and be less than or equal to year_to.
condition string optional Limits the results to the specified condition
Allowed values: new, used
state State optional Limits the results to the specified state/province.
sort_by Sort optional Sorts the results by the specified value.
Allowed values: price, mileage
If sort_by is not specified, results are sorted by internal relevance.
sort_dir Sort optional Direction to sort results based on the value of sort_by.
Allowed values: asc, desc Default: desc
If sort_by is not specified this value will be ignored.
page int optional specifies the number of the page of results to return; if there are no more results a response code of 3 will be returned
Min: 1, Max: 100, Default 1
If page is not set, the default (1) will be used
per_page int optional Specifies the number of results to return per page. If the value specified is outside the allowed range, an error will be returned.
Min: 1, Max: 150, Default 10
If per_page is not set, the default (10) will be used

Query Result Fields

Field Description
id The LemonFree listing ID
title Title of this vehicle listing
vin The VIN (Vehicle Identification Number) of this vehicle listing
year The year of the listing
make_id The make ID of the listing
make The make of the listing
model_id The model ID of the listing
model The model of the listing
trim_id The trim ID of the listing
trim The trim of the listing
condition The condition (either 'New' or 'Used') of the listing
bodystyle The bodystyle of the listing
price The price of the listing
mileage The mileage of the listing
auction Indicates whether the listing is an auction
city The city of the listing
state The state of the listing
state_abbreviation The state abbreviation of the listing
country The country of the listing
zip The zip / postal code of the listing
certified Indicates whether the listing is LemonFree Certified
image The main image of the listing
additional_images Any additional listing images
url The LemonFree.com listing url
listing_count Contains the total number of results available for this request;
NOTE: Although this number is updated periodically, it is a constantly changing value and as such is not guaranteed to be 100% accurate

Sample Results

XML

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns:lf="http://api.lemonfree.com/ns/1.0">
    <lf:request_type>listings</lf:request_type>
    <lf:request_params>
        <lf:attr name="feed">listings</lf:attr>
        <lf:attr name="make">HONDA</lf:attr>
        <lf:attr name="model">accord</lf:attr>
        <lf:attr name="key">[YOUR API KEY]</lf:attr>
    </lf:request_params>
    <lf:response_code>0</lf:response_code>
    <lf:result listing_count="2">
        <lf:item>
            <lf:attr name="id">1HGCP26318A030170</lf:attr>
            <lf:attr name="title">Used 2008 Honda Accord Sdn LX</lf:attr>
            <lf:attr name="vin">1HGCP26318A030170</lf:attr>
            <lf:attr name="year">2008</lf:attr>
            <lf:attr name="make_id">10</lf:attr>
            <lf:attr name="model_id">95</lf:attr>
            <lf:attr name="make">Honda</lf:attr>
            <lf:attr name="model">Accord</lf:attr>
            <lf:attr name="trim">LX</lf:attr>
            <lf:attr name="trim_id">107</lf:attr>
            <lf:attr name="condition">Used</lf:attr>
            <lf:attr name="bodystyle">Sedan</lf:attr>
            <lf:attr name="price">15488</lf:attr>
            <lf:attr name="mileage">26318</lf:attr>
            <lf:attr name="auction">no</lf:attr>
            <lf:attr name="city">Fond Du Lac</lf:attr>
            <lf:attr name="state">Wisconsin</lf:attr>
            <lf:attr name="state_abbreviation">WI</lf:attr>
            <lf:attr name="country">USA</lf:attr>
            <lf:attr name="zip">55017</lf:attr>
            <lf:attr name="certified">true</lf:attr>
            <lf:attr name="image">http://images.lemonfree.com/1HGCP26318A030170_1_img.jpg</lf:attr>
            <lf:group name="additional_images">
                <lf:attr name="image2">http://images.lemonfree.com/1HGCP26318A030170_2_img.jpg</lf:attr>
                <lf:attr name="image3">http://images.lemonfree.com/1HGCP26318A030170_3_img.jpg</lf:attr>
                <lf:attr name="image4">http://images.lemonfree.com/1HGCP26318A030170_4_img.jpg</lf:attr>
                <lf:attr name="image5">http://images.lemonfree.com/1HGCP26318A030170_5_img.jpg</lf:attr>
                <lf:attr name="image6">http://images.lemonfree.com/1HGCP26318A030170_6_img.jpg</lf:attr>
                <lf:attr name="image7">http://images.lemonfree.com/1HGCP26318A030170_7_img.jpg</lf:attr>
                <lf:attr name="image8">http://images.lemonfree.com/1HGCP26318A030170_8_img.jpg</lf:attr>
                <lf:attr name="image9">http://images.lemonfree.com/1HGCP26318A030170_9_img.jpg</lf:attr>
                <lf:attr name="image10">http://images.lemonfree.com/1HGCP26318A030170_10_img.jpg</lf:attr>
            </lf:group>
            <lf:attr name="url">http://www.lemonfree.com/1HGCP26318A030170.html</lf:attr>
        </lf:item>
        <lf:item>
            <lf:attr name="id">1HGCP26709A082927</lf:attr>
            <lf:attr name="title">Used 2009 Honda Accord Sdn EX</lf:attr>
            <lf:attr name="vin">1HGCP26709A082927</lf:attr>
            <lf:attr name="year">2009</lf:attr>
            <lf:attr name="make_id">10</lf:attr>
            <lf:attr name="model_id">95</lf:attr>
            <lf:attr name="make">Honda</lf:attr>
            <lf:attr name="model">Accord</lf:attr>
            <lf:attr name="trim">EX</lf:attr>
            <lf:attr name="trim_id">106</lf:attr>
            <lf:attr name="condition">Used</lf:attr>
            <lf:attr name="bodystyle">Sedan</lf:attr>
            <lf:attr name="price">17488</lf:attr>
            <lf:attr name="mileage">20367</lf:attr>
            <lf:attr name="auction">no</lf:attr>
            <lf:attr name="city">Fond Du Lac</lf:attr>
            <lf:attr name="state">Wisconsin</lf:attr>
            <lf:attr name="state_abbreviation">WI</lf:attr>
            <lf:attr name="country">USA</lf:attr>
            <lf:attr name="zip">55017</lf:attr>
            <lf:attr name="certified">false</lf:attr>
            <lf:attr name="image">http://images.lemonfree.com/1HGCP26709A082927_1_img.jpg</lf:attr>
            <lf:group name="additional_images">
                <lf:attr name="image2">http://images.lemonfree.com/1HGCP26709A082927_2_img.jpg</lf:attr>
                <lf:attr name="image3">http://images.lemonfree.com/1HGCP26709A082927_3_img.jpg</lf:attr>
                <lf:attr name="image4">http://images.lemonfree.com/1HGCP26709A082927_4_img.jpg</lf:attr>
                <lf:attr name="image5">http://images.lemonfree.com/1HGCP26709A082927_5_img.jpg</lf:attr>
                <lf:attr name="image6">http://images.lemonfree.com/1HGCP26709A082927_6_img.jpg</lf:attr>
                <lf:attr name="image7">http://images.lemonfree.com/1HGCP26709A082927_7_img.jpg</lf:attr>
                <lf:attr name="image8">http://images.lemonfree.com/1HGCP26709A082927_8_img.jpg</lf:attr>
                <lf:attr name="image9">http://images.lemonfree.com/1HGCP26709A082927_9_img.jpg</lf:attr>
                <lf:attr name="image10">http://images.lemonfree.com/1HGCP26709A082927_10_img.jpg</lf:attr>
            </lf:group>
            <lf:attr name="url">http://www.lemonfree.com/1HGCP26709A082927.html</lf:attr>
        </lf:item>
    </lf:result>
</response>    

JSON

{
    "response":{
        "request_type":"listings",
        "request_params":{
            "feed":"listings",
            "make":"HONDA",
            "model":"accord",
            "format":"json",
            "key":"[YOUR API KEY]"
        },
        "response_code":"0",
        "result":{
            "listing_count":"2",
            "listings":[
                {
                    "id":"1HGCP26318A030170",
                    "title":"Used 2008 Honda Accord Sdn LX",
                    "vin":"1HGCP26318A030170",
                    "year":"2008",
                    "make_id":"10",
                    "model_id":"95",
                    "make":"Honda",
                    "model":"Accord",
                    "trim":"LX",
                    "trim_id":"107",
                    "condition":"Used",
                    "bodystyle":"Sedan",
                    "price":"15488",
                    "mileage":"26318",
                    "auction":"no",
                    "city":"Fond Du Lac",
                    "state":"Wisconsin",
                    "state_abbreviation":"WI",
                    "country":"USA",
                    "zip":"55017",
                    "certified":"true",
                    "image":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_1_img.jpg",
                    "additional_images":{
                        "image2":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_2_img.jpg",
                        "image3":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_3_img.jpg",
                        "image4":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_4_img.jpg",
                        "image5":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_5_img.jpg",
                        "image6":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_6_img.jpg",
                        "image7":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_7_img.jpg",
                        "image8":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_8_img.jpg",
                        "image9":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_9_img.jpg",
                        "image10":"http:\/\/images.lemonfree.com\/1HGCP26318A030170_10_img.jpg"
                    },
                    "url":"http:\/\/www.lemonfree.com\/1HGCP26318A030170.html"
                },
                {
                    "id":"1HGCP26709A082927",
                    "title":"Used 2009 Honda Accord Sdn EX",
                    "vin":"1HGCP26709A082927",
                    "year":"2009",
                    "make_id":"10",
                    "model_id":"95",
                    "make":"Honda",
                    "model":"Accord",
                    "trim":"EX",
                    "trim_id":"106",
                    "condition":"Used",
                    "bodystyle":"Sedan",
                    "price":"17488",
                    "mileage":"20367",
                    "auction":"no",
                    "city":"Fond Du Lac",
                    "state":"Wisconsin",
                    "state_abbreviation":"WI",
                    "country":"USA",
                    "zip":"55017",
                    "certified":"false",
                    "image":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_1_img.jpg",
                    "additional_images":{
                        "image2":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_2_img.jpg",
                        "image3":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_3_img.jpg",
                        "image4":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_4_img.jpg",
                        "image5":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_5_img.jpg",
                        "image6":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_6_img.jpg",
                        "image7":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_7_img.jpg",
                        "image8":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_8_img.jpg",
                        "image9":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_9_img.jpg",
                        "image10":"http:\/\/images.lemonfree.com\/1HGCP26709A082927_10_img.jpg"
                    },
                    "url":"http:\/\/www.lemonfree.com\/1HGCP26709A082927.html"
                }
            ]
        }
    }
}    

Examples

Query LemonFree API URL to use
All Toyota Camry listings http://api.lemonfree.com/v2/listings/?make=Toyota&model=Camry&key=[YOUR API KEY]
All locations sorted by listing count http://api.lemonfree.com/v2/locations/?sort_by=count&key=[YOUR API KEY]
All locations associated with Toyota listings http://api.lemonfree.com/v2/locations/?make=Toyota&key=[YOUR API KEY]
All locations associated with all 2004-2005 Hyundai listings http://api.lemonfree.com/v2/locations/?make=Hyundai&model=Accent&year_from=2004&year_to=2005&key=[YOUR API KEY]
All locations associated with 2000-2010 Ford Escort SE listings http://api.lemonfree.com/v2/locations/?make=Ford&model=Escort&trim=SE&year_from=2000&year_to=2010&key=[YOUR API KEY]
All locations associated with Pontiac listings in Oregon that are under $20000 http://api.lemonfree.com/v2/locations/?make=Pontiac&state=OR&price_min=0&price_max=20000&key=[YOUR API KEY]