General information

This API is designed for deeper integration (compared to the AJAX API) of audio video search for partner sites.

General scheme of the user's query looks as follows:

1. User — partner site user.
2. Partner — partner server processing a user's query.
3. Tagoo — Tagoo server processing partners queries.

The queries from partner to Tagoo servers for search results is done by HTTP protocol. The answer to partner search query is in XML.

Caching of search results is not recommended, as search results are constantly changing (libks to files won't work or new will be added and so forth).

How do I get partner key?

In order to get partner key one should:

1. Sign up.
2. Generate key and fill in IP adresses, from which queries would be sent.

Queries specification

Queries should be sent from IPs which you wrote in partner search section.

URL pattern for the query:

http://tagoo.ru/api_search.php?type=xml&key=[YOUR_KEY]&for=[audio|video]&page=[PAGE_NUMBER]&on_page=[ON_PAGE]&search_query=[SEARCH_QUERY]

Legend:

1. key — partner key.
2. for — search type (audio or video).
3. search_query — search query.
4. page — page number (1..100).
5. on_page — the number of elements shown on one page (1..20). Default: 10.

XML results specification

For audio search:

<?xml version="1.0" encoding="utf-8"?>
<response>
	<query>[Original query]</query>
	<page>[Page number]</page>
	<on_page>[Number of elements on a page]</on_page>
	<total>[Total number of elements found]</total>
	<page_count>[Number of available pages for browsing]</page_count>
	<safe_query>[Assessing the likelihood of the emergence of content +18]</safe_query>
	<gentime>[Response time]</gentime>
	<results>
		<result>
			<file_url>[Link to the file]</file_url>
			<file_name>[File name]</file_name>
			<page_url>[Link to the page, where the file was found]</page_url>
			<artist>[Artist]</artist>
			<album>[Album]</album>
			<title>[Track title]</title>
			<genre>[Genre]</genre>
			<year>[Year]</year>
			<bitrate>[Bit rate in bits]</bitrate>
			<playtime>[Duration]</playtime>
			<playtime_sec>[Duration in seconds]</playtime_sec>
			<filesize>[Size in bytes]</filesize>
			<fileformat>[File format]</fileformat>
			<filedate>[Date of occurrence of the file on the network]</filedate>
			<snippet>[Snipet of a page where the file was found]</snippet>
		</result>
	</results>
</response>

Legend:

• file_name — you can use file name in order to show title when title field is missing.
• bitrate — example: 128000 (128kbps), can be any value (ie not only widespread 128,192,256,320 etc).
• playtime — in format: hh:mm:ss, example 00:02:35.
• fileformat — file type, for example mp3 or riff. The value may not match the file extension, what indicated is an internal data format.
• filedate — date of occurrence of the file on the network.
• snippet — compiled from data on the page where the file was found. Words matching the request are tagged <b>, other tags are cut.

For video search:

<?xml version="1.0" encoding="utf-8"?>
<response>
	<query>[Original query]</query>
	<page>[Page number]</page>
	<on_page>[Number of elements on a page]</on_page>
	<total>[Total number of elements found]</total>
	<page_count>[Number of available pages for browsing]</page_count>
	<safe_query>[Assessing the likelihood of the emergence of content +18]</safe_query>
	<gentime>[Response time]</gentime>
	<results>
		<result>
			<file_url>[Link to the file]</file_url>
			<file_name>[File name]</file_name>
			<page_url>[Link to the page, where the file was found]</page_url>
			<width>[Width of the video]</width>
			<height>[Height of the video]</height>
			<artist>[Аrtist]</artist>
			<album>[Album]</album>
			<title>[Title]</title>
			<playtime>[Duration]</playtime>
			<playtime_sec>[Duration in seconds]</playtime_sec>
			<filesize>[Size in bytes]</filesize>
			<fileformat>[File format]</fileformat>
			<filedate>[Date of occurrence of the file on the network]</filedate>
			<embed_code>[Embed code]</embed_code>
			<thumb>[Preview picture URL]</thumb>
			<snippet>[Snipet of a page where the file was found]</snippet>
		</result>
	</results>
</response>

Legend:

• file_url — link to the site is not always present, if this video is from videohosting service (for example youtube, this field will be empty).
• file_name — you can use file name in order to show title when title field is missing.
• width, height — size of a video in pixels.
• playtime — in format: hh:mm:ss, example 00:02:35.
• fileformat — file type, for example wmv, flv or mov. The value may not match the file extension, what indicated is an internal data format.
• filedate — date of occurrence of the file on the network.
• embed_code — if the video is embed, in this field embed code is being ketp. You can use it in order to show video to user without redirecting him to the source.
• thumb — Preview picture URL. Always jpg extension, file name always ends by _normal.jpg, if you change normal to small or large you can get smaller or larger picture.
• snippet — compiled from data on the page where the file was found. Words matching the request are tagged <b>, other tags are cut.

Search errors

<?xml version="1.0" encoding="utf-8"?>
<response>
	<error>
		<code>[ERROR_CODE]</code>
		<description >[ERROR_DESCRIPTION]</description>
	</error>
	<results/>
</response>

Possible errors:

1. Invalid partner key (key).

   Cause: You didn't specify key value or made a mistake typing it.

2. Domain is not registered in partner domain list.

   Cause: In this type of search this mistake never occurs.

3. IP adress id not registered in partner IP list.

   Cause: You didn't fill in IP adress in IP adress list, from which queries are sent.

4. IP banned.

   Cause: Your IP banned due to term of service violation or some other cause. Contact Tagoo.ru support.

5. Partner key banned.

   Cause: You banned you partner key at Tagoo.ru.

6. Max number of queries exceed.

   Cause: You have spent all your paid requests. Buy more.

7. Partner key was not confirmed by the administrator.

   Cause: You haven't contacted us to discuss terms of service and activation of the key.