AddView.Online

We encourage all publishers to try our real time live job FeedAPI, which provides excellent content for your users. The live job FeedAPI is fully customisable and easy to use. We also provide accurate reporting on all user activity via your dashboard.

This document will guide you through the FeedAPI details and implementation process. At the end of this document, you can find sample codes.

AdView provides an easy to use API allowing publishers to send the requests through the REST interface.

The FeedAPI is based on the HTTP protocol. This means that any software you write which uses FeedAPI should send HTTP GET request.

Responses formats 

To provide ease of use, the FeedAPI returns the responses in JSON  or XML  formats. To receive the desired response you need to send the requests to one of the following endpoints.

Type URL
XML Response https://adview.online/api/v1/jobs.xml
JSON Response https://adview.online/api/v1/jobs.json
Request parameters 

On each HTTP request, you should send some parameters, many of which are optional. You can find the list of these parameters in the table below.

Status Type Name Description
Mandatory Number publisher It is a unique ID assigned to your account and should always have this value: 2616 (Returns error on invalid values)
Optional String channel You can provide channel name to view individual performance for multiple websites. (Returns error on invalid values)
Mandatory String user_ip The IP address of the user viewing your page. (Ignores tracking on invalid values)
Optional String user_agent The user’s browser agent. (Providing user agent  will improve the tracking on the networks with shared IP)
Optional String keyword This parameter should contain the users search phrase. The FeedAPI will return adverts that contain these terms. (Wildcard characters are supported)
Optional String location Use this parameter to filter adverts by location or postcode. (Wildcard characters are supported)
Optional Number radius This parameter indicates the distance in miles to do Geo-distance match based on the provided location. The accepted value is a number between 0 and 50. In the case of 0, the FeedAPI will do an exact location match. The default is 10.
Optional Number limit Set this parameter to a positive number to define the maximum number of adverts per result. The default is 20, the maximum is 50. (Returns error on invalid values)
Optional Number page It allows you to send the request for the next pages. The default is 1. (Returns error on invalid values)
Optional String sort To change the sort order you can set this parameter to one of these values: daterelevancedistance. The default is relevance. (Returns error on invalid values)
Optional String job_type To filter the adverts you can set this parameter to one of these values: permanenttemporarycontractplacement studentseasonal. The default is all. (Returns error on invalid values)
Optional String categories To filter the adverts by category, you can pass the values from the available categories separated by a pipe sign. The default is all. (Returns error on invalid values)
Optional Number max_age You can provide a positive number to filter the adverts that have been added in last max_age days. (Returns error on invalid values)
Optional Number salary_from By providing a positive number, the FeedAPI returns the adverts with a salary higher than salary_from. (Returns error on invalid values)
Optional Number salary_to By providing a positive number, the FeedAPI returns the adverts with a salary lower than salary_to. (Returns error on invalid values)
Optional String snippet Set this parameter to either highlightbasic or full to change the snippet mode. The default is highlight. (Returns error on invalid values)
Optional String mode To change the search mode you can set this parameter to either advanced or basic. The default is basic. (Returns error on invalid values)

 Please make sure to encode  the GET parameters and also use UTF-8 encoding on the requests.

Using wildcard characters: 

The FeedAPI supports wildcard characters  on keyword and location. Wildcards are special characters that can stand in for unknown characters in a text value.
An asterisk (*) may be used to specify zero or more characters. For example, searching for colo*r would return both color and colour.
A question mark (?) may be used to specify exactly one character. For example, searching for educat?? would return both educated and educator but not education.

Job By Email 

You can also use the FeedAPI to send the jobs to users by email. Job by email is a solution for those who want to send a daily email to the users with the latest jobs. This option lets you personalise the searches for a user by sending a unique user id on each API request. In this way, the FeedAPI result will not be the jobs that have been returned to the user on the previous call. This behaviour will be the same for the next day request, meaning the result won’t contain any jobs previously sent to the user, displaying only fresh job results.

Status Type Name Description
Optional String unique_id It should be a unique id per each request. You can use the user email address or the user unique id in your database.

 When unique_id is present in the request the following parameters will be omitted and there is no need to initialize them: user_ipuser_agentpage.

Response sample 

HTTP response status codes  indicate whether the request has been successfully completed. It will be 200 on success or 422 on failed requests and 503 when application is on maintenance mode.

XML: 
<?xml version="1.0" encoding="UTF-8"?>
<jobs xmlns="https://adview.online/XMLSchema"
      xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="https://adview.online/XMLSchema https://adview.online/XMLSchemaFeedAPI.xsd">
	<total><![CDATA[5148]]></total>
	<per_page><![CDATA[1]]></per_page>
	<current_page><![CDATA[1]]></current_page>
	<last_page><![CDATA[5148]]></last_page>
	<from><![CDATA[1]]></from>
	<to><![CDATA[1]]></to>
	<data>
		<job>
			<title><![CDATA[Sales Executive]]></title>
			<company><![CDATA[]]></company>
			<location><![CDATA[London Greater London England]]></location>
			<postcode><![CDATA[WC2B]]></postcode>
			<snippet><![CDATA[ ... - OTE + Company Car Monday to Saturday with a day off mid week / Rota Sunday (1 in 3) We are currently seeking a Car <span class="highlighted">Sales</span> Executive to join our clients prestige car dealership in North West London. Our client is looking for a dynamic and proactive individual with experience in automotive ... ]]></snippet>
			<url><![CDATA[https://adview.online/dispatch/job/publisher/sales-executive-193?pid=1&psrc=feed&ptkn=b497217a9f4aa019e64e6def3f26ca15a08ab5f1&ptms=eyJpdiI6ImUzU1JCZlwvSDlUUERHZlwvaTZXVUFnXC8rZWVYZlJJQXhVMTdwMThMa1BZM1E9IiwidmFsdWUiOiJ3WVpncUpmWXBtcnRsam9cL051YVpYVFVyODBsZmxzcTZBRVk2RDJIR0FcL2c9IiwibWFjIjoiMWY3MTQ4MDliMzc5NmYwNzVkM2UyYjRiNDNmZTYxYjFhNmNiMGIxYTMwNzJiZGExOTkxYzU3OGZjMTljMTIxOCJ9]]></url>
			<onmousedown><![CDATA[pnpClick(this,'57e00ef02f868');]]></onmousedown>
			<job_type><![CDATA[permanent]]></job_type>
			<salary><![CDATA[15,000-20,000 per annum]]></salary>
			<logo><![CDATA[]]></logo>
			<age><![CDATA[7 hours ago]]></age>
			<age_days><![CDATA[0]]></age_days>
		</job>
	</data>
</jobs>
JSON: 
{
	"total": 5148,
	"per_page": 1,
	"current_page": 1,
	"last_page": 5148,
	"from": 1,
	"to": 1,
	"data": [{
		"url": "https://adview.online/dispatch\/job\/publisher\/sales-executive-193?pid=1&psrc=feed&ptkn=b497217a9f4aa019e64e6def3f26ca15a08ab5f1&ptms=eyJpdiI6ImUzU1JCZlwvSDlUUERHZlwvaTZXVUFnXC8rZWVYZlJJQXhVMTdwMThMa1BZM1E9IiwidmFsdWUiOiJ3WVpncUpmWXBtcnRsam9cL051YVpYVFVyODBsZmxzcTZBRVk2RDJIR0FcL2c9IiwibWFjIjoiMWY3MTQ4MDliMzc5NmYwNzVkM2UyYjRiNDNmZTYxYjFhNmNiMGIxYTMwNzJiZGExOTkxYzU3OGZjMTljMTIxOCJ9",
		"title": "Sales Executive",
		"job_type": "permanent",
		"onmousedown": "pnpClick(this,'57e00ef02f868');",
		"logo": null,
		"age": "7 hours ago",
		"age_days": 0,
		"snippet": " ... - OTE + Company Car Monday to Saturday with a day off mid week \/ Rota Sunday (1 in 3) We are currently seeking a Car <span class=\"highlighted\">Sales<\/span> Executive to join our clients prestige car dealership in North West London. Our client is looking for a dynamic and proactive individual with experience in automotive ... ",
		"salary": "15,000-20,000 per annum",
		"location": "London Greater London England",
		"postcode": "WC2B",
		"company": null
	}]
}
Tracking 

To ensure that the tracking system works correctly place the below code near the results on the page.

Please remember to use the new tracking code when you change the channel.

This code should only be used on websites that comply with our terms & condition.

When you are using Job By Email and you would like to track the number of read emails you should place the image below in your email template. This code generates a transparent image and doesn’t affect your email template.

This code should only be used on websites that comply with our terms & condition.

 Also, each returned result, contains an onmousedown JavaScript code that should be added to the on mouse down event of the job advert link.

The final rendered HTML should be similar to the code below. Also you can test the final result by using the URL Validator.

<div class="job-row">
	<h4 class="job-title">
		<a onmousedown="pnpClick(this,'57e00ef02f868');" href="https://adview.online/dispatch/job/publisher/sales-executive-193?pid=1&psrc=feed&ptkn=b497217a9f4aa019e64e6def3f26ca15a08ab5f1&ptms=eyJpdiI6ImUzU1JCZlwvSDlUUERHZlwvaTZXVUFnXC8rZWVYZlJJQXhVMTdwMThMa1BZM1E9IiwidmFsdWUiOiJ3WVpncUpmWXBtcnRsam9cL051YVpYVFVyODBsZmxzcTZBRVk2RDJIR0FcL2c9IiwibWFjIjoiMWY3MTQ4MDliMzc5NmYwNzVkM2UyYjRiNDNmZTYxYjFhNmNiMGIxYTMwNzJiZGExOTkxYzU3OGZjMTljMTIxOCJ9">
			Sales Executive
		</a>
	</h4>
	<div class="job-description"> ... - OTE + Company Car Monday to Saturday with a day off mid week / Rota Sunday (1 in 3) We are currently seeking a Car <span class="highlighted">Sales</span> Executive to join our clients prestige car dealership in North West London. Our client is looking for a dynamic and proactive individual with experience in automotive ... </div>
	<div class="more-info">
		<span class="company-name"></span>
		<span class="location">London Greater London England</span>
		<span class="postcode">WC2B</span>
		<span class="job-type">permanent</span>
		<span class="salary">15,000-20,000 per annum</span>
	</div>
</div>
Available categories 

The table below contains all valid values for the categories parameter.

Categories
  • Accountancy
  • Administration and Secretarial
  • Aerospace and Aviation
  • Agriculture Fishing, Forestry and Conservation
  • Automotive
  • Banking and Financial Services
  • Catering and Hospitality
  • Charity and Voluntary
  • Construction and Property
  • Customer Service
  • Defence and Military
  • Driving and Transport
  • Education and Training
  • Electronics
  • Energy, Utilities, Oil and Gas
  • Engineering
  • Fashion and Arts
  • FMCG
  • Graduates and Trainees
  • Health, Security and Safety
  • Healthcare and Medical
  • Human Resources and Personnel
  • Information Technology
  • Insurance
  • Journalism, Publishing and Translation
  • Legal
  • Leisure, Tourism and Entertainment
  • Logistics and Warehousing
  • Management and Consultancy
  • Manufacturing and Production
  • Marketing, Advertising and PR
  • Media, Design and Creative
  • Personal Assistant
  • Pharmaceutical
  • Public Sector and Government
  • Purchasing and Procurement
  • Recruitment
  • Retail and Wholesale
  • Sales
  • Scientific
  • Social Care
  • Telecommunications
Search mode 

The search mode defines how the FeedAPI should find the adverts. The search mode can be either advanced or basic. In the basic mode, it returns any advert containing the phrases in the keyword parameter. These phrases can appear in the job title or description. You can use some modifiers to change this behaviour. For example, you can force the FeedAPI to search only for the job title and ignore the phrases in the job description. To use these modifiers, you need to set the search mode to advanced and the modifier should be set in the keyword parameter.

The request below returns the adverts with java developer either in the job title or description. (In basic search mode)

keyword='java developer'

The request below forces the FeedAPI to return the adverts with java developer in their title. (In advanced search mode)

keyword='@(title) java developer'

Listed below are the available modifiers which can be used in conjunction with each other.

Operation Modifier Keyword parameter
Field Search @ @(title,description) developer

By providing the field name, FeedAPI searches only in the given field. There are two field names: title and description.This sample is equal to the basic search mode and will search on both fields.

@(title) developer @(description) bootstrap

It is possible to have different searches on each field. In this example it returns the adverts with developer in their title and bootstrap in their description.

@(description) bootstrap

In this example the FeedAPI returns the adverts with bootstrap in their description.

AND space java developer

By default the FeedAPI returns the adverts containing all the keywords. In this example it returns the adverts containing both keywords of java and developer in either title or description.

@(title) java developer

By having this modifier the FeedAPI returns the adverts containing both keywords of java and developer in their title.

OR pipe java | javascript

By using pipe the FeedAPI returns any advert containing either of the keywords. In this example, it returns the adverts containing java or javascript in either title or description.

@(description) java | javascript

In this example, it returns the adverts containing java or javascript in their description.

NOT dash java -developer

By adding a dash before each keyword the FeedAPI ignores the adverts with the excluded keywords. In this example it returns the adverts containing of java but not developer.

Exact Match quotations "senior developer"

By having quotation marks around the keywords the FeedAPI returns the adverts with the exact matches.

Proximity tilde "junior developer"~3

Having a tilde followed by a number forces the FeedAPI to return the adverts containing the keywords no further than N words.

Quorum Match slash "java c python ruby php"/0.6

Adding a slash following by a floating number between zero and one, forces the FeedAPI to return the adverts containing N percentage of the keywords. In this example it returns the adverts containing 60% of the keywords.

Strict Order less-than developer << java << python

Separating the keywords by two less than signs forces the FeedAPI to match the adverts containing the keywords in the same order.

Combination parentheses (java | javascript) developer

It is possible to combine the modifiers. In this example, it shows the combination of OR and AND operators and returns the adverts containing java developer or javascript developer.

java -(developer | engineer)

The combination of NOT and OR operators. In this example, it returns the adverts containing java but not developer or engineer.

(junior|senior) << (java|python) << (developer|engineer)

The combination of Strict Order and OR operators.

Code samples 

Python: 
# Import libraries
import requests
import urllib

# Set parameters
parameters = { 'publisher' : 2616, 'channel' : '', 'user_ip' : '185.43.110.4', 'user_agent' : 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.108 Safari/537.36', 'keyword' : 'sales', 'location' : 'london', 'limit' : '', 'page' : '', 'sort' : 'relevance', 'job_type' : 'permanent', 'categories' : 'Insurance|Legal' }

# Set URL
url = 'https://adview.online/api/v1/jobs.xml?%s' % urllib.urlencode(parameters)

# Exec and return the result
response = requests.get(url)

# Dump the result
print response.content
PHP: 
// Set parameters
$parameters = array(
	'publisher' => 2616,
	'channel' => '',
	'user_ip' => '185.43.110.4',
	'user_agent' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.108 Safari/537.36',
	'keyword' => 'sales',
	'location' => 'london',
	'limit' => '',
	'page' => '',
	'sort' => 'relevance',
	'job_type' => 'permanent',
	'categories' => 'Insurance|Legal',
);

// Create curl resource
$curl = curl_init();

// Set URL
curl_setopt($curl, CURLOPT_URL, 'https://adview.online/api/v1/jobs.xml' . '?' . http_build_query($parameters));

// Return the transfer as a string
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

// Exec and return the response
$response = curl_exec($curl);

// Close curl resource
curl_close($curl);

// Dump the response
var_dump($response);
CURL: 
curl -G "https://adview.online/api/v1/jobs.xml" \
	--data-urlencode "publisher=2616" \
	--data-urlencode "channel=" \
	--data-urlencode "user_ip=185.43.110.4" \
	--data-urlencode "user_agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.108 Safari/537.36" \
	--data-urlencode "keyword=sales" \
	--data-urlencode "location=london" \
	--data-urlencode "limit=" \
	--data-urlencode "page=" \
	--data-urlencode "sort=relevance" \
	--data-urlencode "job_type=permanent" \
	--data-urlencode "categories=Insurance|Legal"
Encoded URL: 
https://adview.online/api/v1/jobs.xml?publisher=2616&channel=&user_ip=185.43.110.4&user_agent=Mozilla%2F5.0+%28Windows+NT+10.0%3B+Win64%3B+x64%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F78.0.3904.108+Safari%2F537.36&keyword=sales&location=london&limit=&page=&sort=relevance&job_type=permanent&categories=Insurance|Legal
URL Validator 

Once everything was ready, you can use the URL Validation Tool to verify that the tracking code is working fine.

To check that:

  1. Navigate to the rendered page on your website using a browser.
  2. Copy one of the URL by right-clicking on the link and choosing the copy option from the browser menu.
  3. Paste the URL into the URL Validation Tool and click on Validate button.

The tool will show error message in case of any issue or confirmation message when all is working fine.