REST API
Adspect provides a REST API for automating various tasks:
Creating reports: building sales funnels and retrieving click logs
The base URL for all API endpoints is https://api.adspect.net/v1/
. Endpoint descriptions below specify paths relative to this
base URL. HTTP method (verb) comes first, followed by the relative endpoint path, for example:
GET /streams
This endpoint description means making a GET request to https://api.adspect.net/v1/streams
.
The API supports JSON and XML data encoding. Examples below use JSON encoding for simplicity.
Authentication
Adspect API employs HTTP Basic authentication scheme in which API key is supplied as username and password is left blank. You may find your API key in your profile.
Each API request must contain two mandatory headers:
Header |
Value |
Description |
---|---|---|
|
|
Authenticate for an Adspect account with its API key (see below.) |
|
|
Select JSON or XML data encoding, respectively. |
The AUTHKEY
placeholder in the Authorization header must be replaced by a base64-encoded
string composed of the API key and a colon appended to it.
Example code in PHP:
1<?php
2$apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
3$authKey = base64_encode($apiKey . ':');
Tip
For convenience, there’s a readily encoded value of AUTHKEY
available in your profile in the Authorization Header field.
Some HTTP clients offer native support for HTTP Basic authentication scheme which will set the Authorization
header for you (e.g.
Python Requests provides the requests.auth.HTTPBasicAuth
class.) In this case pass
your API key for username and leave password blank. Example for php-curl:
<?php
$apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
$curl = curl_init();
curl_setopt($curl, CURLOPT_USERPWD, $apiKey . ':');
Collections
Certain object properties may take values only from concrete finite sets–collections. The table below lists collection endpoints:
|
Presets for various traffic sources when creating streams. |
---|---|
|
Operating systems for targeting and reporting. |
|
Browsers for targeting and reporting. |
|
Browser engines for targeting and reporting. |
|
Country codes for targeting and reporting. |
|
Language codes for targeting and reporting. |
|
Time zones for targeting and reporting. |
|
Stream modes. |
|
Actions for money and safe pages (see below.) |
|
Sales funnel breakdown columns. |
|
Sales funnel computed metrics. |
|
Click log columns. |
Stream Actions
The following table details available actions for money and safe pages:
Action |
Description |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Managing Streams
A stream is represented as an object with the following properties:
Property |
Type |
Description |
---|---|---|
|
String |
Stream identifier. |
|
String |
Account identifier. Read-only. |
|
String |
Stream name. |
|
String |
Preset name. Write-only. |
|
Array of strings |
Stream tags (up to 32.) |
|
String |
Mode, one of: |
|
String |
Any notes you may want to write down. |
|
Array of objects |
Array of money pages, up to 254, each having the following properties: |
|
String |
Money page rotator, either |
|
Array of exactly one object |
Safe page. Array of exactly one object with the following properties: |
|
Integer or string |
Filtering level, one of: |
|
Boolean |
Enable JavaScript fingerprinting and VLA™ model training. |
|
Boolean |
Enable built-in user agent-based filters. |
|
Boolean |
Allow only unique visitors. |
|
Boolean |
Require touchscreen support (needs JS fingerprinting.) |
|
Boolean |
Allow traffic from mobile apps. |
|
Boolean |
Allow traffic from frames, iframes, and embedded objects. |
|
Array of strings |
Allowed country codes in two-letter format. |
|
Array of strings |
Allowed operating systems. |
|
Array of strings |
Allowed browsers. |
|
Array of strings |
Allowed browser engines. |
|
Array of strings |
Allowed browser language codes. |
|
Array of integers |
Allowed time zones as integer hour offsets from UTC. |
|
Boolean |
Match browser time zone with IP address time zone. |
|
Integer |
Number of first clicks to block (delayed start.) |
|
String |
Skip clicks mode, one of: |
|
String |
IP/ASN list mode, one of: |
|
Boolean |
Blacklist all IP addresses in Review mode. |
|
Integer between 0 and 255 |
IPv4 extrapolation. |
|
Integer between 0 and 64 |
IPv6 extrapolation. |
|
String |
|
|
String |
|
|
String |
|
|
Array of objects |
URL rules. See URL rule object structure description. |
|
Array of objects |
Schedule (dayparting.) See Schedule rule object structure description. |
|
String |
User agent list mode, one of: |
|
String or array of strings |
User agent blacklist. |
|
String or array of strings |
User agent whitelist. |
|
String |
Regular expression for filtering by referrer. |
Example:
{
"stream_id": "1eacc6d0-875f-6f5c-bff8-00162501c2b4",
"account_id": "1eaa2ce5-d4dd-63ec-b8a4-00162501c2b4",
"name": "Example Stream",
"tags": ["Tag1", "Tag2"],
"mode": "Filter",
"notes": "This is an example comment.",
"money_pages": [
{
"page": "https://example.com/offer1?clid={clickid}",
"action": "302",
"arg_passthru": true,
"weight": 10,
"enabled": true
},
{
"page": "https://example.com/offer2?clid={clickid}",
"action": "302",
"arg_passthru": true,
"weight": 20,
"enabled": true
}
],
"rotator": "Split",
"safe_pages": [
{
"page": "safe.html",
"action": "local",
"arg_passthru": true
}
],
"filter_level": "High",
"enable_fp": true,
"enable_ua": true,
"require_unique": true,
"require_touch": false,
"allow_apps": false,
"allow_apps": true,
"countries": ["AE", "HK"],
"os": ["iOS", "macOS"],
"browsers": ["Google Chrome"],
"engines": ["Blink"],
"languages": ["en", "fr", "es"],
"timezones": [-5, -6, -7],
"tz_match_ip": true,
"ip_on_review": true,
"sub_id": "{p:utm_campaign}",
"click_id": "{p:gclid}",
"click_cost": "0.15",
"url_rules": [
{
"param": "zoneid",
"op": "REGEX",
"arg": "[[:alnum:]-_]{8,}",
"enabled": true
}
],
"schedule": [
{
"days": ["Sun", "Sat"],
"since": "15:30:00",
"till": "22:15:00"
}
]
}
URL Rule Object
An URL rule object has the following structure:
{
"param": "gclid",
"op": "REGEX",
"arg": "[[:alnum:]-_]{55,}",
"enabled": true
}
Property |
Type |
Description |
---|---|---|
|
String |
Name of the URL parameter that this rule operates on. |
|
String |
Rule operator. See the operator table below for details. |
|
String |
Operator argument. See the operator table below for details. |
|
Boolean |
Rule is enabled flag. |
Operator |
Argument |
Description |
---|---|---|
|
Optional |
Sets parameter to the value supplied in the rule argument. |
|
Optional |
Renames parameter to the name supplied in the rule argument. |
|
Ignored |
Deletes parameter. |
|
Ignored |
Checks that parameter exists. |
|
Ignored |
Checks that parameter does not exist. |
|
Optional |
Checks that parameter value matches regular expression supplied in the rule argument. |
|
Optional |
Checks that parameter value matches regular expression supplied in the rule argument (case-sensitive). |
|
Optional |
Checks that parameter value does not match regular expression supplied in the rule argument. |
|
Optional |
Checks that parameter value does not match regular expression supplied in the rule argument (case-insensitive). |
|
Optional |
Checks that parameter value equals the rule argument. |
|
Optional |
Checks that parameter value does not equal the rule argument. |
|
Optional |
Checks that parameter value is greater than the rule argument. |
|
Optional |
Checks that parameter value is greater than or equal to the rule argument. |
|
Optional |
Checks that parameter value is less than the rule argument. |
|
Optional |
Checks that parameter value is less than or equal to the rule argument. |
Schedule Rule Object
A schedule (dayparting) rule object has the following structure:
{
"days": ["Sun", "Sat"],
"since": "15:30:00",
"till": "22:15:00"
}
Property |
Type |
Description |
---|---|---|
|
Array of strings |
Days of week the rule applies to. Day is one of: |
|
String |
Allow visitors since time of day in |
|
String |
Allow visitors till time of day in |
List Streams
GET /streams
This endpoint returns a list of streams configured in the account. The list is paginated and ordered by stream name in ascending lexicographic order.
Supported URL parameters:
Parameter |
Type |
Default Value |
Description |
---|---|---|---|
|
Integer |
1 |
Number of page to display. |
|
Integer, from 1 to 100 |
20 |
Number of streams per page. |
|
String |
None |
Output only streams whose names contain the specified substring (case-insensitive.) |
Stream List Metadata
HEAD /streams
This endpoint returns several headers with useful pagination information:
Header |
Type |
Description |
---|---|---|
|
Integer |
Total number of streams. |
|
Integer |
Total number of pages. |
Supported URL parameters:
Parameter |
Type |
Default Value |
Description |
---|---|---|---|
|
Integer, from 1 to 100 |
20 |
Number of queries per page. |
Get Stream
GET /streams/<ID>
This endpoint returns the stream specified by <ID>
.
Create Stream
POST /streams
This endpoint creates and returns a new stream. Send a stream object in request body.
All stream object properties have default values, so you need to specify only those properties
that you want to assign concrete values to, e.g. {"name":"My Stream"}
.
Update Stream
PATCH /streams/<ID>
This endpoint updates the stream specified by <ID>
. Send a stream object in request body.
You need to specify only those properties that you want to change; the rest of them will be left unchanged.
Copy Stream
COPY /streams/<ID>
This endpoint copies the stream specified by <ID>
. Optionally you may send a stream object in
request body–its properties will overwrite properties in the copy, saving you an extra PATCH
call.
Delete Stream
DELETE /streams/<ID>
This endpoint deletes the stream specified by <ID>
.
Integration PHP Files
You may download index.php
, filter.php
, and ajax.php
files for any stream via the following requests:
File |
Endpoint |
---|---|
|
|
|
|
Guest Access to Reporting
Guest access to reporting lets third parties view pre-defined portions of your statistics without having to log into the system. Guess access management is centered around saved report queries:
You create a saved query that specifies allowed report parameters (dates and filters);
The API returns an ID of the saved query;
A guest may then execute this query in the Reporting section by entering the saved query ID in the corresponding field, or by navigating to a link like
https://clients.adspect.io/reporting?query_id=<ID>
, where<ID>
should be replaced with the saved query ID.
Note
At most 100 saved queries may be created.
Saved query is represented by an object with the following properties:
Property |
Type |
Description |
---|---|---|
|
String |
Saved query ID. Read-only. |
|
String |
Saved query owner’s account ID. Read-only. |
|
Integer or string |
Minimum Unix timestamp since which the report will be pulled. |
|
Integer or string |
Maximum Unix timestamp until which the report will be pulled. |
|
String |
Default time zone for displaying date and time. |
|
Array of strings |
Default sales funnel breakdown. |
|
Array of strings |
Filter by stream IDs. |
|
Array of strings |
Filter by IP addresses. |
|
Array of integers or strings |
Filter by autonomous system numbers (ASN).
ASNs may be specified as strings, e.g. |
|
Array of strings |
Filter by country codes in two-letter format. |
|
Array of strings |
Filter by operating systems. |
|
Array of strings |
Filter by browsers. |
|
Array of strings |
Filter by browser engines. |
|
Array of strings |
Filter by sub IDs. |
|
Array of strings |
Filter by click IDs. |
|
Array of strings |
Filter by stream modes. |
|
Array of integers |
Filter by displayed page: |
All properties are optional. If a particular property is not needed, then you may either omit it or set it to null
(or an empty array []
where array values are expected.)
Example:
{
"query_id": "878efbf1-0fb9-4c69-ad36-40e714b0eeeb",
"owner_id": "1eb5991f-a25b-68f4-b171-00162501c2b4",
"date_from": 1577836800,
"date_to": null,
"time_zone": "Asia/Dubai",
"group_by": [],
"stream_id": ["6792f6ce-f153-439f-b223-f58749f1210f"],
"ip_address": [],
"asn": [],
"country_code": ["HK", "AE"],
"os": ["iOS", "macOS"],
"browser": ["Apple Safari"],
"engine": [],
"sub_id": [],
"click_id": [],
"mode": ["Filter"],
"target": []
}
Query List
GET /reports
This endpoint returns a paginated list of created saved queries in the account.
Supported URL parameters:
Parameter |
Type |
Default Value |
Description |
---|---|---|---|
|
Integer |
1 |
Number of page to display. |
|
Integer, from 1 to 100 |
20 |
Number of queries per page. |
Query List Metadata
HEAD /reports
This endpoint returns several headers with useful pagination information:
Header |
Type |
Description |
---|---|---|
|
Integer |
Total number of queries. |
|
Integer |
Total number of pages. |
Supported URL parameters:
Parameter |
Type |
Default Value |
Description |
---|---|---|---|
|
Integer, from 1 to 100 |
20 |
Number of queries per page. |
Get Query
GET /reports/<ID>
This endpoint returns the query specified by <ID>
.
Create Query
POST /reports
This endpoint creates and returns a new query. Send a query object in request body.
Update Query
PATCH /reports/<ID>
This endpoint updates the query specified by <ID>
. Send a query object in request body.
You need to specify only those properties that you want to assign values to; the rest of the properties
will remain unchanged.
Copy Query
COPY /reports/<ID>
This endpoint copies the query specified by <ID>
. Optionally you may send a query object in
request body–its properties will overwrite properties in the copy, saving you an extra PATCH
call.
Delete Query
DELETE /reports/<ID>
This endpoint deletes the query specified by <ID>
.
Reporting API
Adspect Reporting API provides programmatic access to Adspect statistics via two endpoints:
Sales funnel endpoint for creating aggregated reports;
Click log endpoint for extracting raw click by click data.
These endpoints functionally mirror the Reporting section of the Adspect clients area.
Reporting Filters
Both endpoints support filters via URL parameters to narrow down the portion of statistics data to be processed, e.g:
date_from=1672520400&date_to=1675198800&country_code[]=AE&os[]=iOS&os[]=macOS
A report made with such filters will only contain clicks and conversions that match all of the following conditions:
during January 2023:
date_from=1672520400&date_to=1675198800
from United Arab Emirates:
country_code[]=AE
from iOS or macOS devices:
os[]=iOS&os[]=macOS
Tip
You may specify dates and times as human-readable strings instead of Unix timestamps, e.g. 1 Jan 2023
or 2023-01-01
instead of
1672520400
. Adspect will do its best to parse such a date string in a meaningful way.
The following table lists available report filters. All parameters are optional.
Note
Parameters ending with []
are arrays: you may specify several such parameters, and their values will be added together into a
logical OR condition, e.g. os[]=iOS&os[]=macOS
will extract clicks and conversions that came from iOS or macOS devices.
Parameter |
Type |
Description |
---|---|---|
|
String |
Saved query ID for guest access to reports of other Adspect users. |
|
Integer or string |
Minimum Unix timestamp since which the report will be pulled. |
|
Integer or string |
Maximum Unix timestamp until which the report will be pulled. |
|
String |
Time zone for displaying date and time, e.g. |
|
String |
Filter by stream IDs. |
|
String |
Filter by IP addresses. |
|
Integer or string |
Filter by autonomous system numbers (ASN).
ASNs may be specified as strings, e.g. |
|
String |
Filter by country codes in two-letter format. |
|
String |
Filter by operating systems. |
|
String |
Filter by browsers. |
|
String |
Filter by browser engines. |
|
String |
Filter by sub IDs. |
|
String |
Filter by click IDs. |
|
String |
Filter by stream modes. |
|
Integer |
Filter by displayed page: |
Sales Funnel
GET /reports/funnel
This endpoint returns an aggregated report in JSON array per row format. The order of array elements corresponds to the order of
the group_by[]
parameters followed by the order of the metrics[]
parameters.
The following table lists URL parameters specific to the sales funnel endpoint.
Note
Parameters ending with []
are arrays: you may specify several such parameters, and their values will be added together, e.g.
group_by[]=date&group_by[]=stream_id
will result in funnel breakdown first by date and then by stream IDs.
Likewise, metrics[]=clicks&metrics[]=money_hits
will add clicks and money hits metrics to the output, in that order.
Parameter |
Type |
Description |
---|---|---|
|
String, optional |
Add a sales funnel breakdown column to the output. |
|
String, required |
Add a sales funnel metric column to the output. |
Sales Funnel Breakdown Columns
The following table lists available breakdown columns for the group_by[]
URL parameter.
Column |
Description |
---|---|
|
Date in |
|
Month in |
|
Stream ID. |
|
|
|
Country code in two-letter format. |
|
Operating system. |
|
Browser. |
|
Browser engine. |
|
Browser language. |
|
|
|
Stream mode at the moment of the click. |
|
Displayed page: |
|
Mnemonic tag representing a particular block reason. |
Tip
This list may also be obtained via the GET /collections/query-group-by collection endpoint.
Sales Funnel Metrics
The following table lists available sales funnel metrics for the metrics[]
URL parameter.
Important
Please specify only those metrics that you actually need in your API requests.
Metric |
Description |
---|---|
|
Total number of clicks. |
|
Approximate number of unique visitors as per uniqueness of their IP addresses. |
|
Number of visitors that successfully produced a JavaScript fingerprint. This figure may be less than the total number of clicks for various reasons, most often due to inability of dumb bots to run JavaScript code. |
|
Number of visitors that have been shown the money page. |
|
Number of unique visitors that have been shown the money page. |
|
Number of visitors that have been shown the safe page. |
|
General invalid traffic, that is, the number of visitors blocked by superficial filters such as IP address blacklists, user agent matching, targeting, day parting (schedule), etc. |
|
Sophisticated invalid traffic, that is, the number of browser fingerprints that Adspect consciously filtered out as bad traffic. |
|
Clicks missing in action, the figure = the number of visitors that failed to produce or submit a browser fingerprint. As mentioned above, these are often dumb bots with missing JavaScript support. Another common reason is network latency, especially evident in traffic with slow connection rates, e.g. 3G/EDGE, when visitors manage to close the tab or window before their fingerprint is submitted. |
|
Percentage of money hits in the whole click volume. This is the best metric for evaluating traffic quality as a whole and may be used to compare different traffic sources, publishers, ad spots, etc. Especially useful with grouping by sub ID for compiling blacklists of bot-ridden zones, as described in the dedicated paragraph. |
|
Total traffic cost computed as a sum of costs of each click, if passed in a click URL parameter. |
|
Total number of conversions. |
|
Conversion rate = conversions / clicks. |
|
Total revenue computed as a sum of payouts of each conversion, if passed in postback. |
|
Net profit = revenue − cost. |
|
Return on investment = profit / cost. |
|
Cost per click = cost / clicks. |
|
Cost per mille (thousand clicks) = cost / clicks × 1000. |
|
Cost per action = cost / conversions. |
|
Earn per lead = revenue / conversions. |
|
Effective cost per click = revenue / clicks. |
|
Effective cost per mille (thousand clicks) = revenue / clicks × 1000. |
Tip
This list may also be obtained via the GET /collections/query-funnel-metrics collection endpoint.
Examples
Example #1: obtaining basic metrics for all streams, grouped by stream ID:
GET /reports/funnel?group_by[]=stream_id&metrics[]=clicks&metrics[]=money_hits&metrics[]=safe_hits&metrics[]=quality
["1ec5880e-bcb6-49b8-9778-a31d22b70708", "1453", "754", "699", 0.5189263592567103]
["07ac03df-268e-41ff-84ba-adfe2241beb2", "3219", "2034", "1125", 0.6318732525629077]
["7a3d39f7-fe75-431e-8be6-9ea9b56b1e4a", "179", "0", "179", 0]
["9f79b75f-20ef-4654-8141-b8bbb2124ec4", "65", "0", "65", 0]
Example #2: obtaining per-day basic metrics for the stream with ID 07ac03df-268e-41ff-84ba-adfe2241beb2
:
GET /reports/funnel?group_by[]=date&metrics[]=clicks&metrics[]=money_hits&metrics[]=safe_hits&metrics[]=quality&stream_id[]=07ac03df-268e-41ff-84ba-adfe2241beb2
["2024-04-01", "931", "343", "582", 0.3684210526315789]
["2024-04-02", "1166", "829", "300", 0.7109777015437393]
["2024-04-03", "1113", "855", "243", 0.7681940700808625]
["2024-04-04", "9", "7", "0", 0.7777777777777778]
Click Log
GET /reports/log
This endpoint returns a portion of the raw click log in JSON array per row format. The order of array elements corresponds to
the order of the columns[]
parameters.
The following table lists URL parameters specific to the click log endpoint.
Note
Parameters ending with []
are arrays: you may specify several such parameters, and their values will be added together, e.g.
columns[]=timestamp&columns[]=ip_address
will add timestamp and IP address columns to the output, in that order.
Parameter |
Type |
Description |
---|---|---|
|
String, required |
Add a click log column to the output. |
Click Log Columns
The following table lists available click log columns for the columns[]
URL parameter.
Important
Please specify only those columns that you actually need in your API requests.
Column |
Description |
---|---|
|
Date and time of the click or conversion. |
|
IP address of the visitor. |
|
Autonomous system number of the visitor. |
|
Account ID. |
|
Stream ID. |
|
Country code in two-letter format. |
|
Operating system. |
|
Browser. |
|
Browser engine. |
|
List of browser languages. |
|
Click cost or conversion payout. |
|
|
|
|
|
Stream mode at the moment of the click. |
|
Click processing stage: |
|
Displayed page: |
|
List of mnemonic tags that represent particular filtering reasons. |
Tip
This list may also be obtained via the GET /collections/query-log-columns collection endpoint.
Examples
Obtaining today’s click log of the stream with ID 07ac03df-268e-41ff-84ba-adfe2241beb2
:
GET /reports/log?columns[]=timestamp&columns[]=ip_address&columns[]=country_code&columns[]=target&date_from=today&date_to=tomorrow&stream_id[]=07ac03df-268e-41ff-84ba-adfe2241beb2
["2024-04-01 00:00:00", "23.83.90.68", "US", 0]
["2024-04-01 00:00:00", "2a03:2880:30ff:8::33", "SE", 0]
["2024-04-01 00:00:00", "47.128.19.245", "SG", 0]
["2024-04-01 00:00:00", "176.223.109.119", "US", 0]
["2024-04-01 00:00:00", "2a03:2880:20ff:76::33", "US", 0]
["2024-04-01 00:00:00", "89.248.163.208", "NL", 0]
["2024-04-01 00:00:00", "47.128.98.197", "SG", 0]
["2024-04-01 00:00:00", "47.128.25.161", "SG", 0]
["2024-04-01 00:00:00", "95.90.237.130", "DE", 0]
["2024-04-01 00:00:00", "176.5.15.114", "DE", 0]