GnetaGalten.se

What is GG API?

GG API is very simple and flexible mechanism which allows users to acquire various information about advertisements directly from GnetaGalten.se and then display it somewhere in the Internet (personal web-pages, blogs, company websites and so forth).

How to use GG API?

There are several ways to obtain and display information you are interested in:

usage of library of predefined widgets;
usage of HTTP requests and retrieval of information in various formats (JSON, XML or RSS);

Usage of GG API via library of predefined widgets

Ordinary users who are not familiar with web-technologies can in a very simple manner gain benefits from using predefined set of widgets which were specially developed for quick setup and easy usage.

We host a number of sample widgets. Such widgets may be easily customized and used at your website(s).

Just try it!

It is very easy (basically it only takes several minutes to select, customize and setup desired widget).

Usage of GG API via HTTP requests

If you are an advanced WEB user (or developer) then you can obtain required information by means of GG API calls.

In order to continue deeper GG API consideration it is required to get acquainted with a couple of terms.

GG API Call - HTTP request of special format which is charge of information retrieval from GnetaGalten.se. Actually typical GG API Call is an URL like bellows:

http://www.gnetagalten.se/api/REQUEST_TYPE/REQUEST_METHOD.FORMAT?param1=value1[&param2=value2]

where:

REQUEST_TYPE	- GG API request type
REQUEST_METHOD	- GG API request method
FORMAT	- GG API format
paramN=valueN	- additional GG API request parameters

GG API request type - type of information request. Currently there are two request types:

ad - used for retrieval of single advertisement
ads - used for retrieval of list of advertisements

GG API request method - method which is used for information retrieval. Currently only method get is supported.

GG API format - format in which data is sent upon request. Currently there are 3 formats supported:

json (JavaScript Object Notation format)
xml (eXensible Markup Language format)
rss (Really Simple Syndication format)

GG API parameters

Parameter	Format			Request type		Type	Description
Parameter	JSON	XML	RSS	ad	ads	Type	Description
count	+	+	+		+	unsigned integer	count of ads to retrieve
iad	+	+	+	+		unsigned integer	advertisement identifier
uid	+	+	+		+	unsigned integer	user identifier (publisher uid)
region	+	+	+		+	string	region name from which ads are requested
city	+	+	+		+	string	city name from which ads are requested
category	+	+	+		+	string	category name from which ads are requested
callback	+			+	+	string	callback function name (only for JSON format)
rand	+	+			+	boolean ('Y' or '')	whether to obtain ads in random order

GG API formats

There are samples of responses in different formats below.

JSON

API Call: http://www.gnetagalten.se/api/ad/get.json?callback=displayAd&iad=21866

JSON output:


displayAd({"ad":{"id":21866,"title":"Audi TT","text":"Audi TT","publisher":"Daniel","category":"FORDON\/Bilar","region":"V\u00e4stra G\u00f6taland","city":"G\u00f6teborg","person":"p","term":"1 m\u00e5nad","type":"S\u00e4ljes","price":85000,"actual":"Y","expired":"Fri, 07 Aug 2009 10:20:41 +0200","expired_unixtime":1249633241,"URL":"http:\/\/www.gnetagalten.se\/v%C3%A4stra-g%C3%B6taland-g%C3%B6teborg\/fordon-bilar\/audi-tt.html","images":[{"imageURL":"http:\/\/www.gnetagalten.se\/images\/00001\/0\/audi-tt.jpg","thumbnailURL":"http:\/\/www.gnetagalten.se\/images\/00001\/1\/audi-tt.jpg","height":425,"width":640}]}})

There is a very simple example of callback function displayAd available. Please, check it (ad.js) if you are intrested in more detailed examples of usage and how to render simple widget using GG API.

XML

API Call: http://www.gnetagalten.se/api/ads/get.xml?category=fordon&count=1

XML output:

<?xml version="1.0" encoding="UTF-8"?>
<ads>
  <ad>
    <id>21866</id>
    <title>Audi TT</title>
    <text>Audi TT</text>
    <publisher>Daniel</publisher>
    <category>FORDON/Bilar</category>
    <region>VГ¤stra GГ¶taland</region>
    <city>GГ¶teborg</city>
    <person>p</person>
    <term>1 mГҐnad</term>
    <type>SГ¤ljes</type>
    <price>85000</price>
    <actual>Y</actual>
    <expired>Fri, 07 Aug 2009 10:20:41 +0200</expired>
    <expired_unixtime>1249633241</expired_unixtime>
    <URL>http://www.gnetagalten.se/v%C3%A4stra-g%C3%B6taland-g%C3%B6teborg/fordon-bilar/audi-tt.html</URL>
    <images>
      <image>
        <imageURL>http://www.gnetagalten.se/images/00001/0/audi-tt.jpg</imageURL>
        <thumbnailURL>http://www.gnetagalten.se/images/00001/1/audi-tt.jpg</thumbnailURL>
        <height>0</height>
        <width>0</width>
      </image>
    </images>
  </ad>
</ads>

RSS

API Call: http://www.gnetagalten.se/api/ads/get.rss?category=fordon&count=1

RSS output:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>GG RSS</title>
    <description>GG RSS</description>
    <link>http://www.gnetagalten.se/api/ads/get.rss?category=fordon&amp;count=1</link>
    <copyright>InnovateIt.com</copyright>
    <docs>http://cyber.law.harvard.edu/rss/rss.html</docs>
    <generator>GAPI</generator>
    <language>sv</language>
    <lastBuildDate>Tue, 07 Jul 2009 09:28:48 GMT</lastBuildDate>
    <pubDate>Tue, 07 Jul 2009 09:28:48 GMT</pubDate>
    <ttl>15</ttl>
    <item>
      <title>Audi TT</title>
      <description>Audi TT</description>
      <link>http://www.gnetagalten.se/v%C3%A4stra-g%C3%B6taland-g%C3%B6teborg/fordon-bilar/audi-tt.html</link>
      <author>Daniel</author>
      <guid>http://www.gnetagalten.se/v%C3%A4stra-g%C3%B6taland-g%C3%B6teborg/fordon-bilar/audi-tt.html</guid>
      <pubDate>Tue, 07 Jul 2009 11:28:48 +0200</pubDate>
    </item>
  </channel>
</rss>

GG API errors handling

Whenever errors are occured GG API provides you with meaningful information regarding what actually happen so you can deal with it according to your policy of handling errors. Errors are returned exactly in the same format the request was sent.

JSON

API Call (contains error): http://www.gnetagalten.se/api/ad/get.json?callback=displayAd&iad=XYZ

JSON output:


displayAd({"errors":[{"error":{"errno":400,"errtext":"invalid parameter: iad"}}]})

As you can see in case of JSON format errors are returned as indexed array of error objects whereas each error object has two attributes: error number (errno) and error text (errtext). It's up to you whether to suppress error or output it.

XML

API Call (contains error): http://www.gnetagalten.se/api/ads/get.xml?category=nonexistent&count=1

XML output:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>
    <errno>400</errno>
    <errtext>invalid parameter: category</errtext>
  </error>
</errors>

As you can see XML error report follows the same principle as in case of JSON.

RSS

API Call (contains error): http://www.gnetagalten.se/api/ads/get.rss

RSS output:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>GG RSS</title>
    <description>GG RSS</description>
    <link>http://www.gnetagalten.se/api/ads/get.rss</link>
    <copyright>InnovateIt.com</copyright>
    <docs>http://cyber.law.harvard.edu/rss/rss.html</docs>
    <generator>GAPI</generator>
    <language>sv</language>
    <lastBuildDate>Tue, 07 Jul 2009 09:28:48 GMT</lastBuildDate>
    <pubDate>Tue, 07 Jul 2009 09:28:48 GMT</pubDate>
    <ttl>15</ttl>
    <item>
      <title>error 400</title>
      <description>unsufficient paramters set for request</description>
      <author>GAPI</author>
      <pubDate>Tue, 07 Jul 2009 11:28:48 +0200</pubDate>
    </item>
  </channel>
</rss>

GG API Documentation

What is GG API?

How to use GG API?

Usage of GG API via library of predefined widgets

Usage of GG API via HTTP requests

GG API parameters

GG API formats

JSON

XML

RSS

GG API errors handling

JSON

XML

RSS