API Documentation for Logaholic

The API for Logaholic Service Provider Editions (SPE API) provides a framework that allows you to integrate Logaholic user and profile management features into your existing back-end system.

The API has the following features:

  • Install Logaholic core system (multi-license versions only)
  • Add, Edit and Delete user accounts
  • Add and Delete website profiles

General Considerations

The API is installed as a separate component, It is not part of the core Logaholic application and should not be placed inside the main logaholic directory on your server.

Since the API enables ‘remote’ access to user and profile management features, it could pose a security risk if installed incorrectly. The API can be accessed through HTTP GET requests or as a php command line program, depending on where you install it.

Contents

Install

1. To install the Logaholic SPE API, simply copy the logaholic_api folder from your download file to a location on your server.

* If you want to be able to access the API’s functions via HTTP requests, place the “logaholic_api” folder in a web accessible directory.

* If you only want command line access to the API’s functions, choose an non web accessible location on your server and ensure the api folder has the appropriate permission levels.

2. Open the following file in an editor and enter the appropriate values.

/logaholic_api/config-example.php

Make sure that when you are done editing the file to rename config-example.php to config.php

Enter the full absolute system path to the folder that Logaholic is located in
$config[‘path’] = “/var/www/vhosts/domain.com/httpdocs/logaholic“;

Enter the hostname of the mysql server
$config[‘mysqlhost’]= “localhost;

Enter the username of the mysql server
$config[‘mysqluser’]= “mydbname“;

Enter the password of the mysql server
$config[‘mysqlpass’]= “mydbpass“;

Enter the database name of the Logaholic system
$config[‘database’]= “logaholicdb“;

Set a password that will allow you to access the api functions.
If you leave this empty, the API can only be used in a command line environment.
$config[‘api_password’] = “somethingcryptic“;

Log API Calls set to true to log api calls to a file called call_log.
$config[‘log_api_calls’] = false;

Set this to true if you want the API to output json encoded responses.
$config[‘json_output’] = false;

The path to the actual php command on the machine (e.g. C:\PHP\php-cgi.exe) usd for UpgradeLogaholicInstall
$config[‘phpcommand’] = “php“;

The values in red above are examples and should be replaced with your actual values.

The $config[‘path’] variable above should point to the main Logaholic Web Analytics folder, not the directory where you put the API files

That’s it. You are now ready to use the API for user and profile management tasks.

Using the API

In the examples below, we’ll pretend the API files are installed in /var/www/logaholic_api and can be reached via “http://localhost/logaholic_api/” and that we have set up ‘test’ to be the API password.

When accessing the API via HTTP, requests should look something like this:

http://localhost/logaholic_api/index.php?api_password=test&action=action&key=val&key=val

When accessing the API via the command line shell, commands should look something like this:

cd /var/www/logaholic_api; php index.php “api_password=test&action=action&key=val&key=val”

The api_password parameter must be present in all requests. It may only be omitted if you are making requests via the command line only and have left the api_password variable blank in the config.php file. If left blank, any requests via HTTP will fail.

Possible values for action and other key/value pairs will be described below. For the sake of simplicity, we’ll only provide examples of HTTP requests below, but these can all be transformed into the command line equivalents using the example above.

Parameter values containing special characters (like ‘&’) should be urlencoded in the API request

Adding Users

To add users to your logaholic system, you’ll need to make a request using the following parameters:

Parameter Value Notes
action adduser Tells the API we want to add a user
username string – Any alphanumeric string up to 100 characters length
password string Any md5 of your password.
Optionally, you can add the following parameters:
fullname string – The users full name, e.g. John Doe
– Any alphanumeric string up to 100 characters length
email string – The users email address
– Any alphanumeric string up to 100 characters length
accessEditProfile 0 or 1 – Controls whether the user can Edit certain profile settings
– 0 = No, 1 = Yes
– Default 1
accessAddProfile 0 or 1 – Controls whether the user can add new profiles from the Logaholic UI
– 0 = No, 1 = Yes
– Default 0
accessUpdateLogs 0 or 1 – Controls whether the user can manually Update statistics from the Logaholic UI
– 0 = No, 1 = Yes
– Default 0
active 0 or 1 – Controls whether the user account is active and can log in
– 0 = No, 1 = Yes
– Default 1
expires 0 or timestamp – Controls whether the user account expires at a certain point in time. If left to ‘0’, the account never expires. Otherwise, it expires when the unix timestamp value is met.
– Default 0
subscriptionname string – Connect the user to a subscription that is selected by name
– Default null
subscriptionid integer – Connect the user to a subscription that is selected by id
(id always overwrites subscriptionname)
– Default null

A simple API request to add a user could look like this:

http://localhost/logaholic_api/index.php?api_password=test&action=adduser&username=michael&password=mypass

If the operation is successful the script will return the following string:

Success: Added user michael

If the request fails, it will output an error message.

Users added through the API are always non-admin users. This means they can only access profiles they own and cannot edit certain profile settings (like profile name and data collection method), even if accessEditProfile = 1

Editing Users

To Edit a Logaholic user account with the API, you can follow the instructions for adding users above, with these exceptions:

Parameter Value Notes
action edituser Tells the API we want to edit a user
new_username string – Any alphanumeric string up to 100 characters length
– This can be the same as the original username, or a different string, but the parameter must be present

A simple API request to edit a user could look like this:

http://localhost/logaholic_api/index.php?api_password=test&action=edituser&username=michael&password=myNEWpass&new_username=michael

If the operation is successful the script will return the following string:

Success: Edited user michael

If the request fails, it will output an error message.

Deleting Users

To delete a user account, use the following parameters:

Parameter Value Notes
action deleteuser Tells the API we want to delete a user
username string The username of the user you want to delete

A simple API request to delete a user could look like this:

http://localhost/logaholic_api/index.php?api_password=test&action=deleteuser&username=michael

If the operation is successful the script will return the following string:

Success: Deleted profile for www.site1.com
Success: Deleted profile for www.site2.com
Success: Deleted user michael

If the request fails, it will output an error message.

Warning: Deleting a user will also delete any website profiles that belong to that user!!!

Adding Profiles

When adding a website profile to Logaholic through the API, it’s important to note the following:

* If no profile name is given, the API automatically generated a profile name based on the site’s (sub) domain. For example, adding a profile for www.test-me.com, would generate a profile name called ‘wwwtestmecom’.

* Using the API only a limited number of profile settings can be set. Other settings must be changed via the regular UI.

* When a log file location is not provided, we assume the profile will be using javscript tags to collect data.

To add a website profile via the API, you can use the following parameters:

Parameter Value Notes
action addprofile Tells the API we want to add a profile
username string – The username of the account that owns this site
– The username must exist, so always add users before adding profiles
site string Any (sub)domain, e.g. www.mysite.com
Optionally, you can add the following parameters:
profile_name string – The name you want to give this profile in the logaholic system
– If this parameter is missing, the profile name is automatically derived from the site parameter
logfilelocation string – The system path to the log file or the directory that contains the log files for this site
– If this parameter is missing, the profile is set up to use Javascript data collection
splitlogs 0 or 1 – Indicates whether the logfilelocation parameter points to a single log file, or to a directory containing multiple log files
– 0 = Single file, 1 = Directory (multiple files)
– Default 1
splitfilter string or (regular expression) This parameter can be used to avoid unwanted files in the directory to be analyzed. For example, if all your log file names start with “access_log”, use that as the value for this parameter. Only files that (partially) match this value will be analyzed. Leave this blank if all files in the logfilelocation directory need to be analyzed. If you require more complex filtering capabilities, you may also enter a regular expression, between parenthesis. For example (^www\.[xyz|abc.xyz].log.*)
activated 0 or 1 – Controls whether the profile is active and can be updated
– 0 = No, 1 = Yes
– Default 0

An API request to add a profile could look like this:

http://localhost/logaholic_api/index.php?api_password=test&action=addprofile&username=michael&site=www.test-me.com&logfilelocation=/var/www/vhosts/mysite.com/logs/

If the operation is successful, the script will return the following string:

Success: Created profile wwwtestmecom for www.test-me.com

If the request fails, it will output an error message.

Editing Profiles

To edit a website profile via the API, you can use the following parameters:

Parameter Value Notes
action editprofile Tells the API we want to edit a profile
username string – The username of the account that owns this site
– The username must exist, so always add users before adding profiles
site string Any (sub)domain, e.g. www.mysite.com
Optionally, you can add the following parameters:
profile_name string – The name you want to give this profile in the logaholic system
– If this parameter is missing, the profile name is automatically derived from the site parameter
logfilelocation string – The system path to the log file or the directory that contains the log files for this site
– If this parameter is missing, the profile is set up to use Javascript data collection
splitlogs 0 or 1 – Indicates whether the logfilelocation parameter points to a single log file, or to a directory containing multiple log files
– 0 = Single file, 1 = Directory (multiple files)
– Default 1
splitfilter string or (regular expression) This parameter can be used to avoid unwanted files in the directory to be analyzed. For example, if all your log file names start with “access_log”, use that as the value for this parameter. Only files that (partially) match this value will be analyzed. Leave this blank if all files in the logfilelocation directory need to be analyzed. If you require more complex filtering capabilities, you may also enter a regular expression, between parenthesis. For example (^www\.[xyz|abc.xyz].log.*)
activated 0 or 1 – Controls whether the profile is active and can be updated
– 0 = No, 1 = Yes
– Default 0

An API request to add a profile could look like this:

http://localhost/logaholic_api/index.php?api_password=test&action=editprofile&username=michael&site=www.test-me.com&logfilelocation=/var/www/vhosts/mysite.com/logs/

If the operation is successful, the script will return the following string:

Success: Edited profile wwwtestmecom for www.test-me.com

If the request fails, it will output an error message.

Deleting Profiles

To delete a profile from the logaholic system, you can use the following parameters:

Parameter Value Notes
action deleteprofile Tells the API we want to delete a profile
username string – The username of the account that owns this site
– The username must exist, or the profile will not be deleted
site string The (sub)domain you want to delete the Logaholic profile for

An API request to delete a profile could look like this:

http://localhost/logaholic_api/index.php?api_password=test&action=deleteprofile&username=michael&site=www.test-me.com

If the operation is successful the script will return the following string:

Success: Deleted profile wwwtestmecom for www.test-me.com

If the request fails, it will output an error message.

Installing Core Logaholic system

This API feature is only available for customers that have pre-licensed versions that can be installed on multiple machines. If you have a license for one server, this won’t work for you. In that case, just run the [[Logaholic Manual/Set up Wizard |regular install procedure]].

Your logaholic download file will contain 2 main directories:

logaholic

logaholic_api

* Copy the logaholic folder to the location on your server where you want to install the Logaholic Web Analytics system

* Make the logaholic/files directory writeable, see Install Logaholic SHE/SPE Step 3

* Install the logaholic_api folder on your server, see API Installation.

Once the above is done, you can install the main Logaholic system using an API request like this:

http://localhost/logaholic_api/index.php?api_password=test&action=installdb

If the operation is successful the script will return the following string:

Global config written in /somepath/logaholic/files/global.php
Created Database and imported base sql.

If the request fails, it will output an error message.

Setting the Logaholic Report Store Affiliate ID

You can sign up for the Logaholic Report Store affiliate program here:
https://store.logaholic.com/index.php?route=affiliate/login

Once your have your affiliate ID from the Report Store, you can set it using an API request like this:

http://localhost/logaholic_api/index.php?api_password=test&action=set_affiliateid&affiliateid=12345

Where 12345 is your affiliateid.

The request should return this:

Success: Set affiliateid to 12345

If the request fails, it will output an error message.