REST API¶
Adspect provides a REST API for automating various tasks:
- Creating, editing, and deleting streams;
- Downloading integration PHP files;
- Managing guest access to reporting.
The API supports JSON and XML data encoding. Examples below use JSON encoding for simplicity.
Authentication¶
Adspect REST 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 profile.
Each API request must contain two mandatory headers:
Authorization: Basic <authKey>
to authenticate yourself with Adspect;Content-Type
for selecting content data encoding:Content-Type: application/json
for JSON data encoding;Content-Type: application/xml
for XML data encoding.
The <authKey>
field in the Authorization header is formed by base64-encoding
a string composed of the API key and a colon appended to it.
Example code in PHP:
<?php
$apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
$authKey = base64_encode($apiKey . ':');
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.
Endpoints¶
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,
e.g. the description GET /streams
means making a GET request to the https://api.adspect.net/v1/streams
URL.
Collections¶
Certain object properties may take values only from concrete finite sets–collections. Below you will find lists of such values and API endpoints for obtaining them programmatically.
Operating Systems¶
Operating system names are case-insensitive.
GET /collections/os
Android 1
Android 2
Android 3
Android 4
Android 5
Android 6
Android 7
Android 8
Android 9
Android 10
Android 11
Android 12
Android 13
iOS
KaiOS
macOS
Linux
Other
Windows XP
Windows Vista
Windows 7
Windows 8
Windows 8.1
Windows 10
Windows Other
Browsers¶
Browser names are case-insensitive.
GET /collections/browsers
Apple Safari
Facebook app
Google Chrome
Internet Explorer
Microsoft Edge
Mozilla Firefox
Opera
Other
Samsung Internet
Snapchat app
UC Browser
WebView
Yandex Browser
Browser Engines¶
Browser engine names are case-insensitive.
GET /collections/engines
Blink
EdgeHTML
Gecko
Other
Presto
Trident
WebKit
Country Codes¶
GET /collections/countries
Language Codes¶
GET /collections/languages
Time Zones¶
GET /collections/time-zones
Stream Modes¶
Stream modes are case-insensitive.
GET /collections/stream-modes
Filter
– filtering;Review
– on review;Money
– all to money page;White
– all to safe page.
Stream Actions¶
GET /collections/stream-actions
local
– local file (”zero redirect”);proxy
– reverse proxy;fetch
– insert HTML code;iframe
– display in iframe;301
– HTTP 301 redirect;302
– HTTP 302 redirect;303
– HTTP 303 redirect;noop
– no action;refresh
– HTTP Refresh redirect;meta
– HTML meta refresh redirect;return
– custom HTTP response code;php
– execute PHP code;js
– execute JavaScript code;xar
–X-Accel-Redirect
header;xsf
–X-Sendfile
header.
Funnel Groupings¶
Funnel grouping names are case-insensitive.
GET /collections/query-group-by
date
– by date;stream_id
– by stream;asn
– by ASN (autonomous system number);country_code
– by country code;os
– by operating system;browser
– by browser;engine
– by browser engine;sub_id
– by subaccount;mode
– by stream mode;target
– by displayed page number;tag
– by tag.
Managing Streams¶
A stream is represented as an object with the following properties:
stream_id
– stream ID, string, read-only;account_id
– account ID, string, read-only;name
– stream name, string;tags
– stream tags, array of strings;mode
– stream mode, string, eitherFilter
,Review
,Money
, orWhite
;notes
– any notes you may want to write down, string;filter_level
– filtering level, integer:- 0 – essentially off;
- 1 – low;
- 2 – medium;
- 3 – high;
- 4 – paranoid;
enable_fp
– JavaScript fingerprints enabled flag, boolean or integer;allow_apps
– mobile apps allowed flag, boolean or integer;money_pages
– array of one or more (up to 254) money page objects, each having the following format:page
– URL / file path / code (depending on action), string;action
– action to perform for the visitor, string;arg_passthru
– whether to perform URL parameters passthru, boolean;weight
– relative weight for A/B traffic distribution, integer;enabled
– whether this money page is enabled, boolean;
rotator
– money page rotator, string, eitherSplit
orTimer
;safe_pages
– array of exactly one safe page object of the following format:page
– URL / file path / code (depending on action), string;action
– action to perform for the visitor, string;arg_passthru
– whether to perform URL parameters passthru, boolean;
skipClicks
– number of first clicks to send to the safe page (delayed start), integer;cost_parameter
– parameter name for click cost accounting, string;sid_parameter
– sub ID parameter name, string;cid_parameter
– click ID parameter name, string;countries
– array of allowed country strings in ISO 3166-1 alpha-2 format;os
– array of allowed operating system strings;browsers
– array of allowed browser strings;engines
– array of allowed browser engine strings;languages
– array of allowed browser language codes;timezones
– array of allowed time zones as integer hour offsets from UTC;tz_match_ip
– match browser time zone to IP time zone flag, boolean or integer;url_rules
– array of zero or more (up to 64) URL rule objects, each having the following format:param
– URL parameter name, string;op
– rule operator, one of:EXISTS
– parameter exists;NEXISTS
– parameter does not exist;REGEX
– value matches regular expression;IREGEX
– value matches regular expression (case-sensitive);NREGEX
– value does not match regular expression;NIREGEX
– value does not match regular expression (case-insensitive);EQ
– value equals argument;NEQ
– value does not equal argument;GT
– value is greater than argument;GE
– value is greater than or equal to argument;LT
– value is less than argument;LE
– value is less than or equal to argument;ASSIGN
– assign new value to parameter;RENAME
– rename parameter;DELETE
– delete parameter;
arg
– rule argument, string;enabled
– rule enabled flag, boolean;
referer_regex
(obsolete, will be removed) – regular expression for the referer filter, string;ip_on_review
– blacklist IP addresses in “Review” mode flag, boolean or integer.
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
}
],
"ml_precision": 95,
"cost_parameter": "cost",
"sid_parameter": "zoneid",
"cid_parameter": "clickid",
"enable_fp": true,
"paranoid": 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,
"url_rules": [
{
"param": "secretkey",
"op": "EQ",
"arg": "4gHzQvF2IoqeQ",
"enabled": true
}
],
"ip_on_review": false
}
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:
page=1
– sets the number of page to display, defaults to 1;per-page=20
– sets the number of streams per page, from 1 to 100, defaults to 20;name=substr
– lists only streams whose name containssubstr
(case-insensitive.)
Stream List Metadata¶
HEAD /streams
This endpoint returns several headers with useful pagination information:
X-Pagination-Total-Count: 1000
– total number of streams;X-Pagination-Page-Count: 50
– total number of pages.
Supported URL parameters:
per-page=20
– sets the number of streams per page, from 1 to 100, defaults to 20.
Create Stream¶
POST /streams
This endpoint creates and returns a new stream. Send a stream object in request body.
All of the 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.
Integration PHP Files¶
You may obtain index.php
, filter.php
, and ajax.php
files for any stream via the following requests:
index.php
andfilter.php
(both are the same file) –GET https://clients.adspect.ai/getindex.php?sid=<id>
ajax.php
–GET https://clients.adspect.ai/getindex.php?sid=<id>&mode=ajax
Replace <id>
with an actual Adspect stream ID.
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.ai/reporting?query_id=<id>
, where<id>
should be replaced with the saved query ID.
At most 100 saved queries may be created.
Saved query is represented by an object with the following properties:
query_id
– saved query ID, read-only;owner_id
– saved query owner’s account ID, read-only;date_from
– minimum Unix timestamp since which the report will be pulled;date_to
– maximum Unix timestamo until which the report will be pulled;time_zone
– default time zone for displaying date and time;group_by
– default sales funnel grouping, array of strings;account_id
– filter by account IDs, array of strings, read-only;stream_id
– filter by stream IDs, array of strings;ip_address
– filter by IP addresses, array of strings;asn
– filter by ASN, array of integers or strings likeAS65536
orAS1.10
;country_code
– filter by countries, array of strings;os
– filter by operating systems, array of strings;browser
– filter by browsers, array of strings;engine
– filter by browser engines, array of strings;sub_id
– filter by subaccounts, array of strings;click_id
– filter by click IDs, array of strings;mode
– filter by stream modes, array of strings из списка:Filter
,Review
,Money
,White
;target
– filter by displayed paged, array of integers:- 0 – safe page;
- 1–255 – money page with the corresponding ordinal number.
All of the fields are optional. If a particular filter 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": [],
"account_id": ["1eb5991f-a25b-68f4-b171-00162501c2b4"],
"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:
page=1
– sets the number of page to display, defaults to 1;per-page=20
– sets the number of queries per page, from 1 to 100, defaults to 20;
Query List Metadata¶
HEAD /reports
This endpoint returns several headers with useful pagination information:
X-Pagination-Total-Count: 1000
– total number of queries;X-Pagination-Page-Count: 50
– total number of pages.
Supported URL parameters:
per-page=20
– sets the number of queries per page, from 1 to 100, defaults to 20.
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.