Lemonfree API 1.5 (Beta)
Documentation
Last Updated: 2009-07-22Contents
The Lemonfree API provides you with easy access to our vehicle listings and related data. This data is available through a simple and easy to use REST-based system, and returns fully valid XML or JSON results.
Requests to the Lemonfree API require an API key. This key consists of a string of letters and numbers which is unique to each developer, and allows us to track your usage. You can apply to obtain an API key; applications will be reviewed and the key will be activated if the review passes.
The default format for API responses is XML; however it's possible to obtain JSON instead by specifying a "format" parameter with a value of "json" (eg. &format=json)
The Lemonfree API uses per-user daily request quotas. Users are currently limited to 1000 daily requests per API key; each call to an API feed uses 1 request. All quotas are reset every day at 12 AM CST.
Lemonfree currently provides 9 feeds for API users:
- Makes
- Models
- Trims
- Years
- Prices
- Locations
- Listings
- Vehicle Details
- Facts
Text names can be used for make/model/trim/etc, but you might see better performance if you use the ID (IDs are returned by the various feeds)
The Makes feed provides access to all the vehicle makes currently available on Lemonfree.
Base URL: http://api.lemonfree.com/makes
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
The Models feed provides access to all vehicle models for a specific make currently available on Lemonfree.
Base URL: http://api.lemonfree.com/models
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
| make | string|int | required | limits the results to a specific make (name or ID) |
The Trims feed provides access to all vehicle trims for individual models or for a specific model year.
Base URL: http://api.lemonfree.com/trims
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
| model | string|int | required | model name or model ID (obtained from the models feed) |
| year | int | optional | model year |
| make | string | conditional | make name; if model name is used instead of ID then make name is required |
The Years feed provides a list of vehicle years currently available on lemonfree.com for the specified
make, model or trim
Base URL: http://api.lemonfree.com/years
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
| make | string|int | required | make name or make ID (obtained from the makes feed) |
| model | string|int | conditional | model name or model ID (obtained from the models feed); required if trim is also specified, optional otherwise |
| trim | string|int | optional | trim name or trim ID (obtained from the trims feed) |
The Prices feed provides access to pricing groups for the specified make/model/trim/years
currently available on Lemonfree.com
Base URL: http://api.lemonfree.com/prices
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
| make | string|int | required | make name or make ID (obtained from the makes feed) |
| model | string|int | conditional | model name or model ID (obtained from the models feed); required if trim is also specified, optional otherwise |
| trim | string|int | optional | trim name or trim ID (obtained from the trims feed) |
| year_from | int | conditional | 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 | int | conditional | 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 |
The Locations feed provides access to locations (city/state) for the specified make/model/trim/years/prices
currently available on Lemonfree.com
Base URL: http://api.lemonfree.com/locations
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
| make | string|int | required | make name or make ID (obtained from the makes feed) |
| model | string|int | conditional | model name or model ID (obtained from the models feed); required if trim is also specified, optional otherwise |
| trim | string|int | optional | trim name or trim ID (obtained from the trims feed) |
| year_from | int | conditional | 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 | int | conditional | 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 |
| price_min | int | conditional | 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 | int | conditional | 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 |
| state | string | optional | only return cities from the specified state/province. Use the two-letter short code to specify. |
The Listings feed provides access to all vehicle listings on Lemonfree. It returns a maximum of 10 listings per call; if there are more than 10 results for a query, additional results can be obtained by specifying a page number in the query string.
Base URL: http://api.lemonfree.com/listings
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
| make | string | optional | limits the results to a specific make (eg. Ford) |
| model | string | conditional | limits the results to a specific model (eg. Mustang). If specified, make must also be specified. |
| bodystyle | string | optional | limits the results to the specified body style. Available bodystyle values are: SUV Sedan Coupe Truck Minivan Wagon Convertible Hatchback Van Hybrid |
| condition | string | optional | limits the results to either new or used vehicles. Valid values are: new, used |
| year_from | int | conditional | 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 | int | conditional | 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 |
| price_min | int | optional | limits the results to a price range; price_min specifies the lower end of this range. Must be less than or equal to price_max, if both are used |
| price_max | int | optional | limits the results to a price range; price_max specifies the upper end of this range. Must be greater than or equal to price_min, if both are used. |
| mileage_min | int | optional | limits the results to a mileage range; mileage_min specifies the lower end of this range. Must be less than or equal to mileage_max, if both are used. |
| mileage_max | int | optional | limits the results to a mileage range; mileage_max specifies the upper end of this range. Must be greater than or equal to mileage_min, if both are used. |
| 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 there is no distance, results will be limited to only the provided zip/postal code. |
| distance | int | conditional | limits the results to an area around the provided zip/postal code; if distance is specified, zip must also be specified. If no distance is specified or distance is outside of the accepted values, a distance of 5 is used. Valid values are: 5,10,15,20,25,50,75,100, Default: 5. |
| city | string | conditional | limits the results to the specified city. If a city is specified, state/country must also be specified since multiple cities can have the same name. See the description for state and country parameters for more details. |
| state | string | conditional | limits the results to the specified state or province; if state is specified, country must also be specified. For locations in Canada and the US, the two-letter short form can be used if desired (ie. TN, NY); all other countries use the full state name only. Currently only Canada and the US are supported. State search and zip search are mutually exclusive, with zip taking priority - if both zip and state are specified, only the zip search will be performed. |
| country | string | optional | limits the results to the specified country (short form); currently available values for this parameter are: us: USA ca: Canada |
| show_all | string | optional | by default the API only returns vehicles that are not missing any potentially important or useful data (price, mileage, etc.) Including this parameter in your query will tell the API to return all matching vehicles, even those with empty fields. No value is required for this parameter; however if you do specify a value the query will still work. |
| sortby | string | optional | specifies the sort by option. Currently available values for this parameter are: price: Sort result listings by price |
| sortdir | string | conditional | specifies the direction to sort on, ascending or descending. If sortby is not specified, this option has no effect. Valid values are: ASC: ascending DESC: descending |
| 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 (see response codes section). Min: 1. Max: 100. Default: 1. |
| per_page | int | optional | Specifies the number of results to return per page. If the value specified is outside the allowed range, the default will be used. Min: 10, Max: 150, Default: 10 |
Sample Result - XML
<?xml version="1.0" encoding="UTF-8"?>
<response xmlns:lf="http://api.lemonfree.com/ns/1.0">
<lf:request_type>listing</lf:request_type>
<lf:response_code>0</lf:response_code>
<lf:result type="listing" count="10">
<lf:item id="1FAFP42X21F144225">
<lf:attr name="title">Used 2001 Ford Mustang GT</lf:attr>
<lf:attr name="year">2001</lf:attr>
<lf:attr name="make">Ford</lf:attr>
<lf:attr name="model">Mustang</lf:attr>
<lf:attr name="price">11599</lf:attr>
<lf:attr name="mileage">75404</lf:attr>
<lf:attr name="auction">no</lf:attr>
<lf:attr name="city">ONTARIO</lf:attr>
<lf:attr name="state">California</lf:attr>
<lf:attr name="certified">http://www.lemonfree.com/images/LemonFreeCertified-listing.png</lf:attr>
<lf:attr name="image">http://images.lemonfree.com/1FAFP42X21F144225_1_thumb.jpg</lf:attr>
<lf:group name="additional_images">
<lf:attr name="2">http://images.lemonfree.com/1FAFP42X21F144225_2_thumb.jpg</lf:attr>
<lf:attr name="3">http://images.lemonfree.com/1FAFP42X21F144225_3_thumb.jpg</lf:attr>
<lf:attr name="4">http://images.lemonfree.com/1FAFP42X21F144225_4_thumb.jpg</lf:attr>
<lf:attr name="5">http://images.lemonfree.com/1FAFP42X21F144225_5_thumb.jpg</lf:attr>
<lf:attr name="6">http://images.lemonfree.com/1FAFP42X21F144225_6_thumb.jpg</lf:attr>
<lf:attr name="7">http://images.lemonfree.com/1FAFP42X21F144225_7_thumb.jpg</lf:attr>
<lf:attr name="8">http://images.lemonfree.com/1FAFP42X21F144225_8_thumb.jpg</lf:attr>
<lf:attr name="9">http://images.lemonfree.com/1FAFP42X21F144225_9_thumb.jpg</lf:attr>
<lf:attr name="10">http://images.lemonfree.com/1FAFP42X21F144225_10_thumb.jpg</lf:attr>
<lf:attr name="11">http://images.lemonfree.com/1FAFP42X21F144225_11_thumb.jpg</lf:attr>
<lf:attr name="12">http://images.lemonfree.com/1FAFP42X21F144225_12_thumb.jpg</lf:attr>
<lf:attr name="13">http://images.lemonfree.com/1FAFP42X21F144225_13_thumb.jpg</lf:attr>
<lf:attr name="14">http://images.lemonfree.com/1FAFP42X21F144225_14_thumb.jpg</lf:attr>
</lf:group>
<lf:attr name="link">http://www.lemonfree.com/1FAFP42X21F144225.html</lf:attr>
</lf:item>
...
</lf:result>
<lf:total_available>141</lf:total_available>
</response>
Sample Result - JSON
{
"response":{
"requestType":"listing",
"responseCode":0,
"statusMessages":[],
"result":[
{
"id":"19UUA56613A043804",
"title":"Used 2003 Acura TL 3.2",
"year":"2003",
"make_id":"1",
"model_id":"3",
"make":"Acura",
"model":"TL",
"trim":"3.2",
"price":"7641",
"mileage":"114659",
"auction":"no",
"city":"KERNERSVILLE",
"state":"North Carolina",
"certified":"http:\/\/www.lemonfree.com\/images\/LemonFreeCertified-listing.png",
"image":"http:\/\/images.lemonfree.com\/19UUA56613A043804_1_thumb.jpg",
"additional_images":[
"http:\/\/images.lemonfree.com\/19UUA56613A043804_2_thumb.jpg",
"http:\/\/images.lemonfree.com\/19UUA56613A043804_3_thumb.jpg",
"http:\/\/images.lemonfree.com\/19UUA56613A043804_4_thumb.jpg",
...
],
"link":"http:\/\/www.lemonfree.com\/19UUA56613A043804.html"
},
{
"id":"19UUA66227A033422",
"title":"Used 2007 Acura TL",
"year":"2007",
"make_id":"1",
"model_id":"3",
"make":"Acura",
"model":"TL",
"trim":"",
"price":"20739",
"mileage":"59752",
"auction":"no",
"city":"BELLFLOWER",
"state":"California",
"certified":"http:\/\/www.lemonfree.com\/images\/LemonFreeCertified-listing.png",
"image":"http:\/\/images.lemonfree.com\/19UUA66227A033422_1_thumb.jpg",
"additional_images":[
"http:\/\/images.lemonfree.com\/19UUA66227A033422_2_thumb.jpg",
"http:\/\/images.lemonfree.com\/19UUA66227A033422_3_thumb.jpg",
"http:\/\/images.lemonfree.com\/19UUA66227A033422_4_thumb.jpg",
...
],
"link":"http:\/\/www.lemonfree.com\/19UUA66227A033422.html"
},
...
]
}
}
The Details feed provides detailed information about a specific vehicle.
NOTE: This feed is only available
for qualified API accounts. If you have an account and would like to apply for access to this feed, please
contact us detailing your use case.
Base URL: http://api.lemonfree.com/details
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
| listingid | string | required | unique ID/VIN associated with the vehicle, obtained through the listings feed |
Sample Result - XML:
<?xml version="1.0" encoding="UTF-8"?>
<response xmlns:lf="http://api.lemonfree.com/ns/1.0">
<lf:request_type>detail</lf:request_type>
<lf:response_code>0</lf:response_code>
<lf:result type="detail" count="10">
<lf:item>
<lf:attr name="listing_id">1FMYU04185KC05406</lf:attr>
<lf:attr name="title">Used 2005 Ford Escape</lf:attr>
<lf:attr name="year">2005</lf:attr>
<lf:attr name="make">Ford</lf:attr>
<lf:attr name="model">Escape</lf:attr>
<lf:attr name="mileage">47335</lf:attr>
<lf:attr name="price">11988</lf:attr>
<lf:attr name="vehicle_condition">Used</lf:attr>
<lf:attr name="transmission">A</lf:attr>
<lf:attr name="drive">FWD</lf:attr>
<lf:attr name="exterior_color"></lf:attr>
<lf:attr name="body_style">SUV</lf:attr>
<lf:attr name="fuel_type">Gasoline</lf:attr>
<lf:attr name="city">Hawthorne</lf:attr>
<lf:attr name="state">CA</lf:attr>
<lf:attr name="country">USA</lf:attr>
<lf:attr name="zip">90250</lf:attr>
<lf:attr name="description">Just Arrived!!! A winning value! As much as it alters the road,
this limitless SUV transforms its driver*** This One Owner 2005 Ford Escape Limited is a great SUV!!
Finished in Redfire Clearcoat over Black Premium Trimmed Seats...This Escape will not last.. Come in and
drive is 2005 Ford Escape Today!!** FREE Autocheck Vehicle History Report visit WWW.SOUTHBAYFORD.COM to get
your FREE Autocheck Vehicle History Report, and to view our entire inventory of Pre-Owned Automobiles..
***We Buy Cars*** Even if you don't buy from us, we will buy your car or consign it for even more...</lf:attr>
<lf:attr name="seller_name">South Bay Ford Lincoln Mercury</lf:attr>
<lf:attr name="seller_address">5100 W. Rosecrans Avenue</lf:attr>
<lf:attr name="certified">http://http://www.lemonfree.com/images/LemonFreeCertified-listing.png</lf:attr>
<lf:group name="options">
</lf:group>
<lf:attr name="lead_type">basic</lf:attr>
<lf:group name="images">
<lf:attr name="image1">http://images.lemonfree.com/1FMYU04185KC05406_1_pre.jpg</lf:attr>
<lf:attr name="image2">http://images.lemonfree.com/1FMYU04185KC05406_2_pre.jpg</lf:attr>
<lf:attr name="image3">http://images.lemonfree.com/1FMYU04185KC05406_3_pre.jpg</lf:attr>
<lf:attr name="image4">http://images.lemonfree.com/1FMYU04185KC05406_4_pre.jpg</lf:attr>
</lf:group>
</lf:item>
<lf:item>
...
</lf:item>
</lf:result>
<lf:total_available>22424</lf:total_available>
</response>
Sample Result - JSON:
{
"response":{
"requestType":"detail",
"responseCode":0,
"statusMessages":[],
"result":[
{
"listing_id":"19UUA56613A043804",
"title":"Used 2003 Acura TL 3.2",
"year":"2003",
"make":"Acura",
"model":"TL",
"trim":"3.2",
"mileage":"114659",
"price":"7641",
"vehicle_condition":"Used",
"transmission":"A",
"drive":"FWD",
"exterior_color":"Silver",
"body_style":"Sedan",
"fuel_type":"Gasoline",
"city":"KERNERSVILLE",
"state":"NC",
"country":"USA",
"zip":"27284",
"description":"TL 3.2, 4D Sedan, 5-Speed Automatic with Overdrive, Ebony w\/Leather Seat Trim,
Air conditioning, Automatic temperature control, CD player, High-Intensity Discharge Headlights,
Leather Seats, Memory seat, and Power moonroof. Put down the mouse because this 2003 Acura TL is
the car you've been trying to find. Welcome to the A-list. Arrive in style with the TL's bold lines
and stunning good looks. Fashionably late has a new meaning. It scored the top rating in the IIHS
frontal offset test. Why buy retail when you can buy wholesale!
http:\/\/www.wholesalecarsdirect.com Fill out a free credit application at
http:\/\/www.wholesalecarsdirect.com\/credit.htm.",
"seller_name":"Shamburg Auto Sales",
"seller_address":"410 E Bodenhamer St",
"certified":"http:\/\/www.lemonfree.com\/images\/LemonFreeCertified-listing.png",
"options":[],
"lead_type":"basic",
"images":[
"http:\/\/images.lemonfree.com\/19UUA56613A043804_1_pre.jpg",
"http:\/\/images.lemonfree.com\/19UUA56613A043804_2_pre.jpg",
"http:\/\/images.lemonfree.com\/19UUA56613A043804_3_pre.jpg",
"http:\/\/images.lemonfree.com\/19UUA56613A043804_4_pre.jpg",
...
]
}
]
}
}
The facts feed provides access to interesting and useful vehicle-related data available on Lemonfree.com.
Base URL: http://api.lemonfree.com/facts
| Parameter | Type | Occurrence | Description |
| key | string | required | your API key |
| fact | string | required | The type of fact being requested. Currently available values are: avg_price: find the average price on lemonfree.com for a year/make/model |
| year | int | required | Year of the vehicle for which facts are requested |
| make | string | required | Make of the vehicle for which facts are requested |
| model | string | required | Model of the vehicle for which facts are requested |
Qualified API accounts can allow their users to contact vehicle sellers by submitting leads through the API. If you have an API account and are interested in this feature, please contact us with a description of your use case.
There are two types of leads: basic and extended. The type required for a vehicle is indicated in the results from the vehicle details feed. Extended leads require the user to enter additional information. All parameters specified below are required for the lead type indicated
If successful, the response will contain a code of 0 and a message of 'Success'; otherwise the response will contain an error code with additional detail messages
Base URL: http://api.lemonfree.com/lead
| Parameter | Type | Lead Type | Description |
| key | string | all | your API key |
| string | all | User's e-mail address | |
| fname | string | all | User's first name |
| lname | string | all | User's last name |
| zip | string | all | User's zip/postal code |
| phone | int | all | User's phone number, integers only (ie. 3872773621) |
| timeframe | string | extended | Estimated time frame in which the user plans to purchase a vehicle. Allowed values are: 1 week, 2 weeks, 4 weeks, 2 months, 6 months |
| address | string | extended | User's street address |
| city | string | extended | User's city |
| state | string | extended | User's state; use the two-letter state short code (ie. NY) |
| country | string | extended | User's country |
Response Format
<?xml version="1.0" encoding="UTF-8"?>
<response xmlns:lf="http://api.lemonfree.com/ns/1.0">
<lf:request_type>lead</lf:request_type>
<lf:response_code> {RESPONSE CODE} </lf:response_code>
<lf:info>
<lf:message> {DETAILS} </lf:message>
...
</lf:info>
</response>
All feed results have the same basic structure, making it much less time consuming to use multiple feeds
in your application. Feeds usedifferent attributes to describe the data returned; these attributes are
detailed in the individual feed sections below. Here is a list of the common fields found in all results:
NOTE: Attributes enclosed in square brackets (ie. [attribute]) are only available for
certain result types
| Field | Attributes | Description |
| request_type | none | The type of request (or feed) that was made to obtain these results |
| response_code | none | The type of request (or feed) that was made to obtain these results |
| result | type: The type of results being returned. Usually the same as the request_type field; however for feeds where there are different types of possible results (ie. facts feed), this attribute will indicate which type is being returned. count: The number of items returned in this result. |
A container for the individual result items. |
| item | [id]: The ID of a specific result item (if applicable); usually included for use in other requests or feeds | The item field contains the details about a specific result item. If multiple details are returned for a single item, each detail is enclosed in an attr field (described below); otherwise the detail is returned as a string inside the item field. |
| attr | various | The attr field contains an individual detail for a result item. This field is present if a result item contains more than one individual detail. Attributes for this field can vary depending on which feed was used; for possible values, see the individual feed sections below. |
| group | name: Label for the group | The group field is a container for a group of details, such as additional images for a listing |
| total_available | none | Contains the total number of results available for the given request; if this number isn't available then this field will not be present. NOTE: Although this number is updated periodically, it is a constantly changing value and as such is not guaranteed to be 100% accurate. |
| Value | Description |
| make | make name |
| listing_count | number of listings currently on Lemonfree.com for this make |
| Value | Description |
| model | model name |
| listing_count | number of listings currently on Lemonfree.com for this model |
| Value | Description |
| title | Title of this vehicle listing |
| year | Vehicle year |
| make_id | Vehicle make ID |
| model_id | Vehicle model ID |
| make | Vehicle make text |
| model | Vehicle model text |
| trim | Vehicle trim text |
| price | Vehicle price / current bid (auction detail indicates which) |
| mileage | Vehicle mileage |
| auction | "yes" if the vehicle is an auction, "no" if it is a direct sale. |
| city | City where the vehicle is located | state | State where the vehicle is located |
| certified | Present if vehicle is sold by a certified dealer; contains a URL for the certified dealer logo image |
| image | Thumbnail image of the vehicle, if available |
| additional_images | any additional images available for the vehicle, up to 39 additional images |
| link | URL to the details page for this vehicle on Lemonfree.com |
| Value | Description |
| avg_price | The average price on Lemonfree.com for the given year/make/model. (only with avg_price request) |
| country | Indicates which country (and currency) the average price relates to. (only with avg_price request) |
Every result returned will have a response code field, and potentially an error message as well (contained in the response_err field). The following is a list of possible response codes and what error message (if any) they return.
| Code | Error Message | Description |
| 0 | none | This code indicates that the request was successful, and the response should contain valid results. |
| 1 | Invalid API key | The API key specified in the request either does not exist, or the account it belongs to hasn't yet been validated. |
| 2 | Maximum daily quota reached | The daily request quota associated with this API key has been reached |
| 3 | No data available | The request made did not return any results |
| 4 | API service unavailable | There was a problem communicating with the API server; usually only occurs if the API is undergoing maintenance. |
| 5 | Required parameters missing | Some of the required parameters for the feed are not present |
| 6 | Feed requires special permission | The feed is only available to qualified API accounts; contact us to apply for this status |
| 7 | Incorrectly formatted lead details | Some details for the lead were invalid / not correctly formatted (ie. phone, email); see response for additional detail |
| 8 | Lead could not be submitted | The lead was rejected; see response for additional detail |