» Custom API

API Documentation

Vast.com Integration Guide

Vast's API allows web developers quickly to create powerful search tools. Our high performance index is accessible through an easy-to-learn, easy to implement protocol which is fully Atom compliant and modeled after Google's GData.
Our API is the most flexible way that you can interact with our data, and also the one requiring the most technical sophistication on your part.
What you need to do:

Get an API Key
Construct and send requests to the Vast API
Parse the XML response from the Vast API

Get an API Key
Requests to the Vast API require an API key. This is a string of letters and numbers that uniquely identifies you, and it allows us to track uniquely your activity (and allocate your affiliate revenue).
To get an API key, go to url here
Construct and send requests to the Vast API
The Vast API V2.0 is fully Atom compliant and based on the GData protocol. At this time the only supported format is Atom; requests for other formats will generate errors.
There are three feeds available:

Listings: This feed is used to search for, and retrieve listings from the Vast database.
Attributes: This feed is used to retrieve metadata about available attributes and common values
Categories: This feed is used to retrieve metadata about Vast categories.

"Great," you ask, "so what do I do with this 'useful' bit 'o information?"
NOTE: Now is the time on Sprokets when we provide lots of examples of the API in action. In all of these examples we have omitted the apikey=<your_api_key> argument. The API will respond in the absence of this argument, but it will return sample data. When constructing your queries include the apikey=<your_api_key> argument in every single call. Thank you.

Listings Feed:
Most of your queries to the Vast API will be to the listings feed. It returns a set of items from our database that match a query you supply with your API request. The minimum request to the listings feed is very simple. Try it out:
http://data.vast.com/listings
It returns some listings, but they're pretty random in nature. But hey, you didn't ask for anything in particular. Whaddya expect?
Fortunately, we long ago recognized that a random collection of items isn't interesting to most people, so we allow you to parameterize your request to find what you want. Let's take a look at the standard parameters available to modify any search:

Category

Categories and subcategory can be specified in the URL path after /-/. As you'd expect, the acceptable categories can be found in the Categories feed.

q

You may pass a full-text query string with the 'q' parameter. Note that Vast does not support quoted string searches.

start-index

A 1-based index of the first result to be retrieved. This defaults to 1.

max-results

The maximum number of results to be retrieved. This defaults to 10.

tlocation

Short for "text location," this gives you an opportunity to supply a free-text name of a location near which you'd like to search. Almost any city, state or region specification will work, e.g "San Francisco", "San Francisco, CA", "94110". Values passed to tlocation will be translated internally into a city, then a range search will be performed from that city. For strict zip code based searches, use the zip parameter.

zip

The specific zip code in which to search. Provide with range=0 to search exactly in that zip code.

range

The distance, in miles, from the specified location for which results should be returned. Set to 0 to get results from the specified location only. This will include the entire city specified, but not neighboring cities. This defaults to 50 miles.

sort

An integer representing the desired sort order for results. For most categories, the following are available options:

Price Ascending
Price Descending
Distance Ascending
Distance Descending
Mileage Ascending
Mileage Descending

There are some category specific modifications / notes about this:

Jobs Category:: 1 & 2 sort by Salary, not Price
Vacation Rentals:: 1 & 2 sort by Nightly Rate
Personals:: 1 & 2 sort by Age

Also, 5 & 6 only apply to cars, though we're looking at creative ways to apply them to personals and pets as well.

Drilldown Parameters

In addition to these standard parameters that apply to all listing categories, many categories support additional parameters for further refining searches. These can be discovered using the Attributes Feed. See below for more information.

Retrieving a Specific Listing

You can also request a specific listing if you know the listing ID. The ID field and Self Link from the Listings Feed contains URIs formatted in this fashion.
http://data.vast.com/listings/<listingid>/-/<category>

Let's make this considerably clearer by taking a look at some examples:

Get some cars (whatever cars, wherever they are – just show me 10 cars):: http://data.vast.com/listings/-/cars
Get some cars within 50 miles (default radius) of San Francisco:: http://data.vast.com/listings/-/cars?tlocation=san+francisco
Get some cars in the 94110 ZIP code:: http://data.vast.com/listings/-/cars?zip=94110&range=0
Enough about cars. Let's try retrieving the second page of "merchandise," assuming the default page size of 10 listings. This is our generic category of stuff for sale. Please forgive the legacy name of the category, which is item_vehicle. We realize that "vehicle" kind of implies cars, and we are ashamed of this transgression.: http://data.vast.com/listings/-/item_vehicle?start-index=11
Subcategories? Sure. Let's get the first page of bicycles:: http://data.vast.com/listings/-/item_vehicle/bike
Keywords? Let's look for fishing stuff:: http://data.vast.com/listings/-/item_vehicle?q=fishing
Toyota Parts & Accessories?:: http://data.vast.com/listings/-/item_vehicle/part_accessories?q=toyota

You get the idea...
So what do you get back from such a query? It will look something like this:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns='http://www.w3.org/2005/Atom' xmlns:o='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:v='http://data.vast.com/ns/listings'>
<id>http://data.vast.com/listings/-/item_vehicle/bike</id>
<link rel="self" type="application/atom+xml" href="http://data.vast.com/listings/-/item_vehicle/bike?apikey=13994064513277853211021421514151"/>
<updated>2007-05-10T23:12:45+02:00</updated>
<title type='text'>Vast Item Vehicle, Bike</title>
<o:totalResults>4680</o:totalResults>
<o:startIndex>1</o:startIndex>
<o:itemsPerPage>10</o:itemsPerPage>
<v:extra/>
<entry>
<id>http://data.vast.com/listings/-811318497455918701/-/item_vehicle/bike?apikey=13994064513277853211021421514151</id>
<updated>2007-05-07T23:45:10+02:00</updated>
<published>2007-05-07T23:45:10+02:00</published>
<author>
<name>buyit.dfw.com</name>
</author>
<title type="text">Gently Used Ladies Mountain Bike</title>
<v:vertical>general</v:vertical>
<v:category>item_vehicle%2Cbike</v:category>
<v:location>

<v:state>TX</v:state>
<v:country>United States</v:country>
<v:zip>76132</v:zip>
<v:distance>0</v:distance>
<v:city>Fort Worth</v:city>
<v:lat>32.671991</v:lat>
<v:lon>-97.432311</v:lon>
<v:address></v:address>
</v:location>
<v:price type="money" symbol="$" currency="USD" value="120">$120</v:price>

<v:currency type="text">USD</v:currency>
<link rel="self" type="application/atom+xml" href="http://data.vast.com/listings/-811318497455918701/-/item_vehicle/bike?apikey=13994064513277853211021421514151"/>
<link rel="http://cache.vast.com" type="text/html" title="Cache" href="http://www.vast.com/cache.php?s=uxiRQLN90JOGFrwbFGZB"/>
<link rel="via" type="text/html" title="buyit.dfw.com" href="http://www.vast.com/details/generic/ob-3Qk4YWvBsUZkF7DMQ9SbBhGJBrs2tGubS5t7N7sYkUCzdYuwuEwUmcuBOw==/?ivp="/>
<link rel="alternate" type="text/html" title="Gently Used Ladies Mountain Bike" href="http://www.vast.com/details/generic/ob-3Qk4YWvBsUZkF7DMQ9SbBhGJBrs2tGubS5t7N7sYkUCzdYuwuEwUmcuBOw==/?ivp="/>
<v:domain_name type="text">buyit.dfw.com</v:domain_name>
<v:year type="number"></v:year>
<v:image_url type="image/jpeg">http://images.vast.com/getimage/tools/createThumbnail.php?vertical=generic&id=-811318497455918701&w=128&h=128</v:image_url>
<v:hasimage type="boolean">yes</v:hasimage>
<v:description type="text">Ladies Mountain Bike in EXCELLENT CONDITION. Purple/Silver/Black - Added accessories</v:description>

<content type="html"><img src="http://images.vast.com/getimage/tools/createThumbnail.php?vertical=generic&id=-811318497455918701&w=128&h=128"><ul><li>description:Ladies Mountain Bike in EXCELLENT CONDITION. Purple/Silver/Black - Added accessories</li><li>price:$120</li><li>currency:USD</li><li>country:United States</li><li>state:TX</li><li>zip:76132</li><li>city:Fort Worth</li></ul></content>
</entry>
...
</feed>

Attributes Feed:
Most searches can be further refined by applying additional constraints. Our Vast.com "drilldown" UI is a good example of how this can work.
The attributes feed allows you to see what the available attributes are for further refining a search, and also shows common values and item counts for each of the available attributes.
All attributes in the attributes feed may be used as parameters to refine results in both the listings and attributes feeds. The id of any v:attribute element in the attributes feed is the name of a parameter; valid values are specified as the ids of nested v:value elements.
Attributes of type "money" and "number" in the attributes support arbitrary range searching. The v:value elements for these attributes represent sample ranges, but are not the only ones available. To search for any arbitrary range, use the format param=low-high. For example:
http://data.vast.com/listings/-/cars?year=2003-2007
The lower and upper attributes on the v:attribute element of type "money" or "number" delimit a suggested search range for that attribute, but not strict limits. In particular there will often be records with values higher that the upper limit; this number is meant as the lower bound of an "or more" search. These values are good values to use as the limits of a slider control, provided that the slider allows an "infinity" setting beyond the upper number.
Let's look at some examples:

Get all attributes for the category Cars:: http://data.vast.com/attributes/-/cars
Get all attributes present on Toyota Cars. Note that the Make attribute will not be included in the results because it's assumed (Toyota):: http://data.vast.com/attributes/-/cars?make=Toyota

You get the idea…

What will the results look like? Something like this. Note that the <content> fields have been truncated for brevity. Today this content payload is not very useful, but in time we plan to return html for drawing drilldowns.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns='http://www.w3.org/2005/Atom' xmlns:o='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:v='http://data.vast.com/ns/attributes'>
<id>http://data.vast.com/attributes/-/item_vehicle/bike?apikey=13994064513277853211021421514151</id>
<link rel="self" type="application/atom+xml" href="http://data.vast.com/attributes/-/item_vehicle/bike?apikey=13994064513277853211021421514151"/>
<updated>2007-05-10T23:25:36+02:00</updated>
<title type='text'>Vast Item Vehicle, Bike</title>
<o:totalResults>4680</o:totalResults>
<o:startIndex>1</o:startIndex>
<o:itemsPerPage>10</o:itemsPerPage>
<v:extra/>
<entry>

<id>http://data.vast.com/attributes/location/-/item_vehicle/bike?apikey=13994064513277853211021421514151</id>
<title type='text'>Location</title>
<updated>2007-05-10T23:25:36+02:00</updated>
<author>
<name>www.vast.com</name>
</author>
<v:attribute id="location" type="text">
<v:value id="Los-Angeles--CA" count="107">Los Angeles, CA</v:value>
<v:value id="Memphis--TN" count="21">Memphis, TN</v:value>
<v:value id="Raleigh--NC" count="19">Raleigh, NC</v:value>

<v:value id="Kailua-Kona--HI" count="18">Kailua Kona, HI</v:value>
<v:value id="Bridgeport--CT" count="12">Bridgeport, CT</v:value>
<v:value id="Trumbull--CT" count="9">Trumbull, CT</v:value>
<v:value id="Glendale--AZ" count="8">Glendale, AZ</v:value>
<v:value id="Calgary--Canada" count="425">Calgary, Canada</v:value>
<v:value id="Edmonton--Canada" count="253">Edmonton, Canada</v:value>
<v:value id="Peterborough--United-Kingdom" count="60">Peterborough, United Kingdom</v:value>
<v:value id="Bristol--United-Kingdom" count="54">Bristol, United Kingdom</v:value>
<v:value id="Brighton--United-Kingdom" count="39">Brighton, United Kingdom</v:value>

<v:value id="Bexhill--United-Kingdom" count="25">Bexhill, United Kingdom</v:value>
<v:value id="Burgess-Hill--United-Kingdom" count="23">Burgess Hill, United Kingdom</v:value>
<v:value id="Littlehampton--United-Kingdom" count="22">Littlehampton, United Kingdom</v:value>
<v:value id="Raleigh--Canada" count="17">Raleigh, Canada</v:value>
<v:value id="Winnipeg--Canada" count="16">Winnipeg, Canada</v:value>
<v:value id="Haro--Spain" count="15">Haro, Spain</v:value>
<v:value id="Bedminster--United-Kingdom" count="13">Bedminster, United Kingdom</v:value>
<v:value id="Winterbourne--United-Kingdom" count="11">Winterbourne, United Kingdom</v:value>
<v:value id="Trowbridge--United-Kingdom" count="10">Trowbridge, United Kingdom</v:value>

<v:value id="Northampton--United-Kingdom" count="7">Northampton, United Kingdom</v:value>
<v:value id="Other-United-Kingdom" count="1644">Other United Kingdom</v:value>
<v:value id="Other-Canada" count="622">Other Canada</v:value>
</v:attribute>
<content type="html">…</content>

</entry>
<entry>
<id>http://data.vast.com/attributes/price/-/item_vehicle/bike?apikey=13994064513277853211021421514151</id>
<title type='text'>Price</title>
<updated>2007-05-10T23:25:35+02:00</updated>
<author>
<name>www.vast.com</name>
</author>
<v:attribute id="price" type="money" symbol="$" currency="USD" lower="0" upper="1001" median="70">
<v:value id="0-21" count="517" min="0" max="21">less than $21</v:value>
<v:value id="21-30" count="355" min="21" max="30">$21 - $30</v:value>

<v:value id="31-40" count="403" min="31" max="40">$31 - $40</v:value>
<v:value id="41-50" count="439" min="41" max="50">$41 - $50</v:value>
<v:value id="51-70" count="569" min="51" max="70">$51 - $70</v:value>
<v:value id="71-110" count="740" min="71" max="110">$71 - $110</v:value>
<v:value id="111-1000" count="1208" min="111" max="1000">$111 - $1,000</v:value>
<v:value id="1001-max" count="216" min="1001" max="max">$1,001+</v:value>
<v:value id="unknown" count="233" >unknown</v:value>
</v:attribute>
<content type="html">...</content>

</entry>
<entry>
<id>http://data.vast.com/attributes/category/-/item_vehicle/bike?apikey=13994064513277853211021421514151</id>
<title type='text'>Category</title>
<updated>2007-05-10T23:25:34+02:00</updated>
<author>
<name>www.vast.com</name>
</author>
<v:attribute id="category" type="text">
</v:attribute>
<content type="html"><ul></ul></content>

</entry>
</feed>

Categories Feed:
This feed is the single, authoritative source for the current Vast category hierarchy. We make it available for two cases:
You may query it manually to get the most up-to-date list of categories available through the Vast API
-or-
If you're building a very flexible and generic application that exposes the entire Vast catalog, you may query it programmatically to determine dynamically the list of categories to display.
There is only one way to request this feed, and there are no parameters that modify the request (but remember your API key):
http://data.vast.com/categories
When you submit this request, you will receive a reply that looks something like the following:

<feed>
<id>http://data.vast.com/categories</id>
<updated>2007-05-09T12:03:01-0700</updated>
<entry>
<id>http://data.vast.com/categories</id>
<updated>2007-05-09T12:03:01-0700</updated>
<title type="text">Vast Categories</title>
<v:category count="54289" id="service" name="Services">
<v:category count="243" id="musician" name="Musicians"/>
<v:category count="82" id="wanted" name="Wanted"/>
...
</v:category>
<v:category count="707929" id="ticket" name="Tickets">
<v:category count="177215" id="concert" name="Concert"/>
<v:category count="159612" id="theater" name="Theater"/>
...
</v:category>
<v:category count="4494890" id="cars" name="Cars"/>
<v:category count="281479" id="rentals" name="Rentals">
<v:category count="156925" id="apartment" name="Apartments"/>
<v:category count="595" id="wanted" name="Wanted"/>
...
</v:category>
<v:category count="3144582" id="real_estate" name="Real Estate">
<v:category count="146" id="wanted" name="Wanted"/>
<v:category count="3274" id="farm" name="Farm"/>
...
</v:category>
<v:category count="11734574" id="personals" name="Personals"/>
...
</entry>
</feed>

So what are we looking at?
This is a feed with a single entry. That entry is a hierarchical list of Vast categories – categories that are acceptable as parameters when constructing requests to other Vast feeds.
Some of these categories, such as Services, Tickets, Rentals and Real Estate, have subcategories. Some, such as Cars and Personals, do not.
This feed changes very infrequently, but once again it is the single authoritative source for the current Vast category hierarchy.

Parse the XML responses from the Vast API
What you do with our replies is limited only by your imagination. The data are returned to you as an XML payload, which you may process and render as you wish.