Service (API)

Most important task of Agentarius is, of course, providing the data over interfaces to the members of the community, to rate the requests to their own websites.

For these purposes, several interfaces are available, that registered users can use:

• Independent exchange formats like XML, JSON or Text over an URL
• .NET-Web-Service over the SOAP protocol for requesting data e.g. from ASP.NET applications
• Web-Service over the XML-RPC protocol for requsting data from XML-RPC capable programs

For the data access a service key is necessary for each website or program, which wants to request the data. Members can create these keys in their profile.

Limitation

The data access is not limited initially. Depending on the growth of the requested amount of data, a limitiation is possible, because this project is privately financed

Independent exchange formats

Information about a User-Agent-String can be requested with the following URL:

Parameters:

The User-Agent-String should be transferred URL-encoded, to avoid errors on the request. Thereby all special characters will be converted in ASCII sequences. Each server-side script-language and Javascript, the client-side script-language, supports corresponding methods, wich accomplish this.
Here some hints:

• Javascript: encodeURI
• ASP.NET: UrlEncode
• PHP: urlencode
• Java URLEncoder

Following formats are supported at the moment:

Error handling

In case an error occures while executing a request, the error message will be stored in a special error element of the particular exchange format.

An error will occure also, if the requested User-Agent-String is not yet listed in the database. The new string will be stored in the database as 'new/unknown'.

Examples

↵ XML XML

<?xml version="1.0" encoding="utf-8" ?>
<useragentinfo app="agentarius.net" ver="1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.agentarius.net/service/useragentinfo.xsd">
  <useragent id="212">
    <string><![CDATA[Googlebot/2.1 (+http://www.google.com/bot.html)]]></string>
    <group id="12">
      <name>Google</name>
      <website>http://www.google.com</website>
      <rating>1</rating>
      <rating_count>1</rating_count>
      <category id="2" name="Search Engine" />
    </group>
  </useragent>
  <error></error>
</useragentinfo>

↵ JSON JSON

{
   'useragentinfo':{
      'useragent':[{
         'id':'212',
         'string':'Googlebot%2f2.1+(%2bhttp%3a%2f%2fwww.google.com%2fbot.html)',
         'group':{
            'id':'12',
            'name':'Google',
            'website':'http%3a%2f%2fwww.google.com',
            'rating':'1',
            'rating_count':'1',
            'category':{
               'id':'2',
               'name':'Search Engine',
               }
            }
      }],
      'Error':''
   }
}

↵ Text Text

useragent-id=212
useragent-string=Googlebot/2.1 (+http://www.google.com/bot.html)
group-id=12
group-name=Google
group-website=http://www.google.com
group-icon=google.gif
group-rating=1
group-rating-count=1
category-id=2
category-name=Search Engine
error=

.NET-Web-Service

Additionally to the abovementioned request methods, ASP.NET developers, for example, are able to use a .NET-Webservice, wich delivers the data over the SOAP protocol.

The webservice is accessible over following URL:

Using the menu entry 'Add Service Reference...' in Microsoft Visual Studio 2005, for example, the service can be bind to personal ASP.NET projects.

GetUseragentInfo2

Determine all information about an User-Agent-String and stores the IP-Address if the request belongs to a robot.

Parameter

Return

The method returns a DataSet object named UserAgentData. This DataSet contains a DataTable named UserAgent with following columns:

Error handling

The DataSet, wich the method returns, contains in case of an error a DataTable named Error.

An error will occure also, if the requested User-Agent-String is not yet listed in the database. The new string will be stored in the database as 'new/unknown'.

GetUseragentInfo

Determine all information about an User-Agent-String without storing the IP-Address

Parameter

The return value und the error handling is equivalent to the method GetUseragentInfo2.

GetUseragentInfoMulti

Determine information about multiple User-Agent-Strings.

Parameter

The parameter UserAgentInfoParameter expects a generic list of data structures named UserAgentInfoParamStruct, as defined as follows:

(Example in Visual Basic .NET)

Public Structure UserAgentInfoParamStruct
    Public UserAgentString As String
    Public IPAddress As String
End Structure

...

Dim lst As New List(Of UserAgentInfoParamStruct)
Dim stc As New UserAgentInfoParamStruct

stc.UserAgentString = "This_Is_A_UserAgent"
stc.IPAddress = "192.168.0.1"

lst.Add(stc)

...

Return

The method returns a DataSet object named UserAgentData. All User-Agent-String, wich could be detected successfully, are stored inside the DataSet in a DataTable named UserAgent (definition see method GetUseragentInfo2).

Error handling

The DataSet, wich the method returns, contains in case of an error a DataTable named Error.

An error will occure also, if the requested User-Agent-String is not yet listed in the database. The new string will be stored in the database as 'new/unknown'.

Web-Service (XML-RPC)

Beside the SOAP-Web-Service a service over the XML-RPC-Protocol is avaliable, wich was implemented by Charles Cook's XML-RPC.NET solution.

XML-RPC-Web-Services are based on data structures (structs) wich can be transmitted, processed an returned. The data transportation uses the HTTP protocol and XML.

The webservice is accessible over following URL:

Following methods are implemented:

GetUseragentInfo2

Determine all information about an User-Agent-String and stores the IP-Address if the request belongs to a robot.

Parameter

Return

The method returns a data structure named UserAgentInfoStruct:

(Example in Visual Basic .NET)

Public Structure UserAgentInfoStruct
    Public UserAgentString As String
    Public UserAgentID As Integer
    Public UserAgentAddDate As String
    Public UserAgentAddUser As String
    Public UserAgentSource As String
    Public UserAgentGroupComputed As Boolean
    Public GroupID As Integer
    Public GroupName As String
    Public GroupWebsite As String
    Public GroupRating As Double
    Public GroupRatingCount As Integer
    Public CategoryID As Integer
    Public CategoryName As String
    Public CategoryHuman As Integer
    Public RequestDuration As String
    Public Status As String
End Structure

Error handling

The service implements the fault exceptions, defined in the XML-RPC spec.

An error will occure also, if the requested User-Agent-String is not yet listed in the database. The new string will be stored in the database as 'new/unknown'.

GetUseragentInfo

Determine all information about an User-Agent-String without storing the IP-Address

Parameter

The return value und the error handling is equivalent to the method GetUseragentInfo2.

GetUseragentInfoMulti

Determine information about multiple User-Agent-Strings.

Parameter

The parameter UserAgentInfoParameter expects an array of data structures named UserAgentInfoParamStruct, as defined as follows:

(Example in Visual Basic .NET)

Public Structure UserAgentInfoParamStruct
    Public UserAgentString As String
    Public IPAddress As String
End Structure

Return

The method returns an array of data structures named UserAgentInfoStruct (see method GetUseragentInfo2):