API Documentation

    Table of Contents

• User authentication
• User data management
• Sites management
• Reports
• Download PHP code example of simple application based on current API. (Installation Guide)
• PHP Example demo.

To use the API you should be authorised via http authorization. For test needs API engine uses the user currently logged in to clickaider.com.
You can use all the following examples with proper results using demo account. To log into the demo account use the following login/password: demo/demo.

Table of Contents

• Signup
  • users.checkLogin ( login ) [ Example1, Example2 ]
  • users.checkEmail ( email ) [ Example1, Example2 ]
  • getTimezoneByIP ( ip ) [ Example ]
  • getTimezones ( ) [ Example ]
  • users.signup ( firstname, lastname, email, time_zone, login, pass[, no_confirm[, bReceiveNotices]] ) [ Example1, Example2 ]
  • users.confirmSignup ( unihash ) [ Example ]
  • users.forgotPassword ( email ) [ Example1, Example2, Example3 ]
  • users.del ( unihash ) [ Example ]
  • users.ban ( unihash ) [ Example ]
• Profile management
  • users.getList ( fields[, page[, num[, meta[, orderby]]]] ) [ Example1, Example2 ] Fields list: login,unihash,firstname,lastname,email,time_zone,date_registered,date_lastlogin,type,site_count
  • userSettings.getProfile ( unihash ) [ Example ]
  • userSettings.setProfile ( unihash[, firstname[, lastname[, time_zone[, bReceiveNotices]]]] ) [ Example1, Example2 ]
  • userSettings.changePass ( unihash, pass ) [ Example ]
  • userSettings.changeEmail ( unihash, email ) [ Example1, Example2 ]
  • userSettings.confirmEmail ( unihash ) [ Example ]

Table of Contents

• Site profile management
  • sites.getList ( unihash[, page[, num[, meta]]] ) [ Example1, Example2 ]
  • sites.add ( unihash, name, url, time_zone ) [ Example1, Example2 ]
  • sites.del ( unihash, sites_ids ) [ Example ]
  • sites.ban ( unihash, sites_ids ) [ Example ]
  • siteSettings.update ( unihash, site_id, name, url, time_zone ) [ Example ]
  • siteSettings.getProfile ( unihash, site_id ) [ Example ]
  • siteSettings.getTrackingCode ( unihash, site_id[, track_links[, track_forms[, track_intellitxt[, tags]]]] ) [ Example1, Example2] Tracking code help
  • getLogos ( ) [ Example ]
• Clicks log subscription
  • siteSettings.getLogFilesubScriptionStatus ( unihash, site_id ) [ Example ]
  • siteSettings.subscribeLogFile ( unihash, site_id ) [ Example ]
  • siteSettings.setLogFileSubscriptionType ( unihash, site_id, type ) [ Example1, Example2 ]
  • siteSettings.unsubscribeLogFile ( unihash, site_id ) [ Example ]

Table of Contents

Whenever date/time is required, it should be provided in MM/DD/YYYY+HH:MM form.
To limit request with some date/time period use the following parameters:
&date_from=MM/DD/YYYY+HH:MM&date_to=MM/DD/YYYY+HH:MM
or
&date_from=MM/DD/YYYY+HH:MM&date_to=now
or
&date_from=MM/DD/YYYY+HH:MM
Alternative way to specify date/time period is to specify it relatively in date_relative parameter. If request contains parameter date_relative, then parameters date_from and date_to are ignored.
Default value for date_relative is last7days if neither date_relative nor date_from/date_to are specified.
&date_relative=today | yesterday | last2days | this_week | last7days | last_week | this_month | last30days | last_month | all

For trend reports we have parameter group_by_date.
&group_by_date=hour | day | week | month | hourly_for_day | daily_for_week | hourly_for_week

Request can contain filters. There are 2 types of filters - regular and excluded. To use the filters you should specify prefix "f_", for excluded filters - prefix "fe_". You can also filter by one or several values that should be comma separated.
If you want to add filters on fields "ip" and "se" and excluded filter on field "country" the request should be like this:
&f_ip=[IPs in decimal format separated by comma]&f_se=[ids of Search Engine names in string table separated by comma]&fe_country=[ids of countries separated by comma]

How to retrieve values of Search Engine ID or page URL ID or country ID?
To do that you need to create report using function report.getTop() which get list of IDs and strings sorted by clicks count and grouped by those Search Engine field or page URL field or country field. In general you can use result of any report that contains values IDs.

You can also filter by certain strings instead of their IDs. To do that you should send API call by HTTP POST method and specify parameter bStringFilters. See function CAWS::call() in file class.CAXML.php from PHP code examples of API calls
Also you should change filter request rule like this:
&f_ip[]=[ip in string format]&f_ip[]=[another ip in string format]&f_se[]=[Search Engine name]&f_se[]=[another Search Engine name]&fe_country[]=[2 letter country id]&fe_country[]=[another 2 letter country id]


Fields for which lookups are specified in current API must be filtered only by their identifiers whenever HTTP method is used and bStingFilters specified or not. See section Fields' lookup data

Fields specification:

Simple fields that can be filtered and grouped. Field name Field caption ip Visitors` IP / Hostname page Page file File dir Directory entry_page Entry Page entry_file Entry File entry_dir Entry Directory entry_host Entry Host entry_domain Entry Domain domain Domain page_title Page Title host Host entry_ref Entry Referer entry_ref_file Entry Referer File entry_ref_dir Entry Referer Directory entry_ref_host Entry Referer Host entry_ref_src Entry Referer Source ad Advertiser banner_size Banner Size ad_format Ad Format ad_type Ad Type banner_number Banner Number se_key Search Keyword se Search Engine se_offset Search Engine Offset click_target Click Target link_target Link Target link_text Link Text link_file Link File link_directory Link Directory link_host Link Host link_domain Link Domain form_target Form Action form_name Form Name form_content Form Content is_link Is Link link_posx Link Position X link_posy Link Position Y banner_posx Banner Position X banner_posy Banner Position Y click_class Ad Class is_linkunit Link unit/Ad unit visitor Visitor session Session ID session_time Session Time session_pages Session Pages time_on_the_page Time on the Page browser Browser ref Referer ref_host Referer host referer_file Referer file orig_ref_domain Original Referer Site ua User Agent browser_class Browser Class os OS country Country region Region city City language Language campaign Campaign border_color Border color bg_color Background color link_color Link color url_color Url color txt_color Text color client Client channel Channel page_channel Page Channel 1 page_channel2 Page Channel 2 page_channel3 Page Channel 3 entry_page_channel Entry Page Channel 1 entry_page_channel2 Entry Page Channel 2 entry_page_channel3 Entry Page Channel 3 link_channel Link Channel 1 link_channel2 Link Channel 2 link_channel3 Link Channel 3 uv1 User Variable 1 uv2 User Variable 2 uv3 User Variable 3		Combined fields that can be grouped, but not filtered. Grouping will be actually applied only to the first field from the list of combined fields passed in request, but data will be shown for all the combined fields. The following fields can be used in parameter group_by. For example: &group_by=title_c_page Field name Field caption Combined fields title_c_page URL / Page Title (page, page_title, ) location City / Region / Country (city, region, country, ) link_target_c_text Link Target / Link Text (link_target, link_text, ) country_region Region / Country (region, country, )	Mandatory filters will be applied automatically if the following fields are specified for grouping: See filter values explanation under the table. Grouping By Field    Default Filtered Fields    Filter Value ad_format click_class 1 is_linkunit ad 1 channel ad ad 1 10 client ad 1 form_target click_class 3 form_name click_class 3 form_content click_class 3 link_text ad 10
	Fields By Category Category Name Field Field Caption Site title_c_page domain host file dir entry_page entry_file entry_dir page_title URLs Domains Hosts Files Directories Entry Pages Entry Files Entry Directories Page Titles Referers entry_ref orig_ref_domain Entry Referers Entry Referer Sites Advertisers ad click_class ad_format Advertisers Classes Ad Formats Search Engines se_key se Search Keywords Search Engines Targets click_target link_target_c_text Click Targets Link Targets Google Adsense is_linkunit channel client Link Types Channels Clients IntelliTXT channel link_text Channels Hover Words Form Info form_target form_name form_content Form Actions Form Names Form Contents Link Info link_target_c_text link_text link_domain link_host link_file link_directory Link Targets Link Text Link Domains Link Hosts Link Files Link Directories Location country country_region location language Countries Regions Cities Languages Audiences ip IPs Browsers ua browser browser_class os User Agents Browsers Browser Classes Operation Systems User Variables uv1 uv2 uv3 User Variable 1 User Variable 2 User Variable 3		Filter values explanation Advertisers (ad): id caption 0 unknown 1 AdSense 2 Yahoo Publishers Network 3 Amazon 4 AdBrite 5 Begun 6 YandexDirect 7 FastClick 8 Bidvertiser 9 AuctionAds 10 IntelliTXT 11 ShoppingAds Click classes (click_class) id caption 0 n/a 1 Advertisment 2 Link 3 Form

Report's fields (using following functions you can easily recreate structure of existing ClickAider reports and create new reports which are not currently added to GUI interface):
• reportFields.getSimpleFields ( ) [ Example ]
• reportFields.getCombinedFields ( ) [ Example ]
• reportFields.getFieldsByCategories ( ) [ Example ]
• reportFields.getMandatoryFilters ( ) [ Example ]

Fields' lookup data:
• reportFieldsLookups.getAdvertisers ( ) [ Example ]
• reportFieldsLookups.getCountries ( ) [ Example ]
• reportFieldsLookups.getClickClasses ( ) [ Example ]

Reports:
• report.getClick ( unihash, site_id, click_id[, time_zone] ) [ Example ]
• report.getLog ( unihash, site_id[, page[, num[, time_zone[, date_relative[, date_from[, date_to[, bStingFilters[, f_*[, fe_*[, type[, fields]]]]]]]]]]]] ) [ Example1, Example2]
• report.getTop ( unihash, site_id, group_by, countfields[, page[, num[, time_zone[, date_relative[, date_from[, date_to[, bStingFilters[, f_*[, fe_*]]]]]]]]]] ) [ Example1, Example2 ]
• report.getTrend ( unihash, site_id, group_by_date, countfields[, page[, num[, time_zone[, date_relative[, date_from[, date_to[, bStingFilters[, f_*[, fe_*]]]]]]]]]] ) [ Example1, Example2 ]
• report.getTrendOfItems ( unihash, site_id, group_by_date, countfield, group_by, item_ids[, page[, num[, time_zone[, date_relative[, date_from[, date_to[, bStingFilters[, f_*[, fe_*[, bIsPercent]]]]]]]]]]]] ) [ Example1, Example2 ]
• report.getTrendOfTopItems ( unihash, site_id, group_by_date, countfield, group_by[, page[, num[, time_zone[, date_relative[, date_from[, date_to[, bStingFilters[, f_*[, fe_* ]]]]]]]]] ) [ Example ]

Table of Contents