Vivastreet API
VivaAPI is a facility for querying Vivastreet directly. Through a simple programmer's interface it's easy to get information to display
on your own web pages.
This document explains the technical details of how to use VivaAPI. The intended audience is developers who are tasked with
programming a web application to use the VivaAPI. i
Implementation
VivaAPI is implemented as SOAP transactions through HTTPS. See http://www.w3.org/TR/soap12 for details of the SOAP standard.
In RPC fashion a SOAP request is sent to Vivastreet with any necessary parameters (e.g. category) and a SOAP response with data is
returned. That data can then be stored, organized, and displayed in any way desired.
All details of VivaAPI are defined in a standard WSDL (Web Services Description Language) file. See http://www.w3.org/TR/wsdl
for details of this standardii. The XML Schema for all data types is included. Many software development platforms can read this file
and create client code automatically. Strictly typed platforms can generate classes matching VivaAPI data types (Schema elements,
simpleTypes, and complexTypes). All functions take simple standard XML Schema data types for input.
Technical Considerations
Here are some things to consider when implementing a VivaAPI SOAP client:
● Every detail the application needs to know is in http://api.vivastreet.com/vivasoap.wsdl
● All XML from the client is expected to be in the UTF-8 (UNICODE) character set. Other common character sets should work but
UNICODE is preferred.
● All XML from VivaAPI will be in the UTF-8 character set.
● All date/time values are in the XML Schema dateTime formatiii which is based on the ISO 8601 standard. Be sure to format and
convert to the appropriate time zone for display. This functionality is built into most development platforms.
● Some query results should temporarily be stored locally for reuse. Data such as Vivastreet countries, regions, categories, and
subcategories change very infrequently. To speed up your web site, save bandwidth, and limit the load on Vivastreet this data
should be stored within your web site. They can be retrieved once per day without concern of becoming stale. At the most they
should be retrieved only once per user session.
The Basics
Vivastreet ads are organized by country, region, category, and subcategory. VivaAPI has four operations (analogous to application
functions) to get lists of these criteria for querying ads. Each returns an id or code with a descriptive name. Country id must always
be determined first because it's required for every other operation. With that regions, categories, and subcategories can be retrieved.
They'll be provided in the appropriate language for the country. Subcategories can be retrieved all at once or per category.
With this information anywhere from 1 to 100 ads can be retrieved at a time. For each query of ads (GetAds operation) pass a country
id, the number of ads to be retrieved, and any region, category, and subcategory codes to limit by. If a code is not passed it will not be
filtered. For example, if no region code is passed the results will be across all regions in the country. If two category codes and 5
subcategory codes are passed the ads will be from all of those categories and subcategories.
The API
● All input and output parts are sent in the SOAP Body portion of the message.
● Every input part must be passed. Inputs designated as optional must be passed empty if no value is desired (e.g. <category/>).
● All inputs of region, category, and subcategory are string lists. As defined by the XML Schema standard iv, any number of codes
can be passed separated by a space (as shown below with elipses).
● All _id and _code values are unique within their context.
● The key value is the unique key provided by Vivastreet when your registration was approved.
Operation:
Purpose:
Input Parts:
Ouput Parts:
GetCountries
Get a list of available countries
<key>key</key>
<countries>
<country>
<id>country_id</id>
<name>name</name>
</country>
...
</countries>
Operation:
Purpose:
Input Parts:
GetRegions
Get a list of available regions within a country
<key>key</key>
<!-- required -->
<country>country_id</country>
<!-- required -->
<regions>
<region>
<code>region_code</code>
<name>name</name>
</region>
...
</regions>
Ouput Parts:
Operation:
Purpose:
Input Parts:
Ouput Parts:
Operation:
Purpose:
Input Parts:
Ouput Parts:
<!-- required -->
GetCategories
Get a list of available categories
<key>key</key>
<!-- required -->
<country>country_id</country>
<!-- required -->
<categories>
<category>
<code>category_code</code>
<name>name</name>
</category>
...
</categories>
GetSubCategories
Get a list of available subcategories by category
<key>key</key>
<!-- required -->
<country>country_id</country>
<!-- required -->
<category>category_code ...</category>
<!-- optional -->
<categories>
<category>
<code>category_code</code>
<name>name</name>
<subcategories>
<subcategory>
<code>subcategory_code</code>
<name>name</name>
</subcategory>
...
</subcategories>
</category>
...
</categories>
Operation:
Purpose:
Input Parts:
GetAds
Get recent ads
<key>key</key>
<!-- required -->
<country>country_id</country>
<!-- required -->
<region>region_code ...</region>
<!-- optional -->
<category>category_code ...</category>
<!-- optional -->
<subcategory>subcategory_code ...</subcategory> <!-- optional -->
<resultlimit>number_of_ads</resultlimit> <!-- required, int from 1 to 100 --> Ouput Parts:
<ads>
<ad>
<id>ad_id</id>
<url>url to ad on Vivastreet</url>
<title>Link title</title>
<posted>date posted</posted>
<details>ad content</details>
</ad>
...
</ads>
Sample Code
PHP 5
The file sample.php uses PHP 5 with built-in SOAP support and tidy for easily viewing the SOAP transactions. It requires PHP 5 to
be compiled with “--enable-soap –-with-tidy”. If the request and response output sections of sample.php are removed tidy isn't
required. Replace the value of $key near the top of the file with your actual VivaAPI key.
sample.php has been tested successfully on Linux with Apache 1.3 and PHP 5.0.3.
PHP 4
The easiest way to use SOAP with PHP 4 is with nuSOAP. nuSOAP is written entirely in PHP classes, therefore requiring no special
extensions. This is a very good option for use with shared hosting providers. nuSOAP can be downloaded from
http://sourceforge.net/projects/nusoap/. A simple tutorial can be found at http://www.scottnichol.com/nusoapprogwsdl.htm.
The file sample_nusoap.php uses PHP 4 and nuSOAP. It assumes nuSOAP's PHP files are in PHP's library search path or in the
current directory. Replace the value of $key near the top of the file with your actual VivaAPI key.
sample_nusoap.php has been tested successfully on Linux with Apache 1.3, PHP 4.3.11, and nuSOAP 0.6.9.
iThis document generally uses technical terms specific to SOAP, WSDL, and XML. See the standards documentation at
http://www.w3.org for definitions.
iiWSDL is currently a submission to the World Wide Web Consortium. It is not yet a “recommendation” (i.e. recommended for use
as a standard). It is, however, well supported and unchanged since early 2001. Being based on standard XML and not having an
adequate substitute it is likely to be supported by a variety of software platforms for the foreseable future.
iiihttp://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#dateTime. See http://www.w3.org/TR/NOTE-datetime
and http://www.ietf.org/rfc/rfc3339.txt for additional details.
ivhttp://www.w3.org/TR/2004/REC-xmlschema-0-20041028/#ListDt