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: date , relevance , distance . 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: permanent , temporary , contract , placement student , seasonal . 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 highlight , basic 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_ip
, user_agent
, page
.
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 | ||
---|---|---|
|
|
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) 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:
- Navigate to the rendered page on your website using a browser.
- Copy one of the URL by right-clicking on the link and choosing the copy option from the browser menu.
- 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.