This website uses cookies. Okay

Yourbrowser.is API - browser details detection

Yourbrowser.is API Version 1.1 Reference

Purpose

yourbrowser.is API enables you to detect end user browsing environment including web browser details, browser plug-ins, presence of ad blockers (if any), login status on social networks, mobile device, and more. The tool also lets you measure the user’s connection speed. Refer to the section "Checks" for a detailed list of detections that can be made.

The API is available with yourbrowser.is PRO Account priced at $19/month or $209/year.

Usage

To check end user's browsing environment follow the below mentioned steps:

  1. Create a checker.
  2. Send its URL to the user with a request to open it.
  3. Get a list of reports collected by the checker.
  4. Retrieve selected report.

Read further for more details.

API usage is capped at 100 requests per minute. If you have larger needs, please contact us.

Base URL and Formats

The API is available at the following URL and can be accessed via HTTP or HTTPS.

http://api.yourbrowser.is/

All requests are sent via POST.
Requests and responses are in JSON format.

Authentication

In order to use the API you need to obtain an API key. This key must be included with all requests.
You can find your API key in the Settings section of yourbrowser.is user panel (assuming you're a PRO Account user).

Statuses

Every API response begins with a status. Below is a list of all possible statuses and their descriptons.

Status Description
OK Request accepted, response follows.
CREATED [create_checker only] The checker has been created successfully
UPDATED [create_checker only] The checker configuration has been updated successfully
ERROR Something went wrong. This status always comes with error code and error texts, see table below.

Errors

Error codes, texts and descriptions:

ERRNO ERRTXT Description
1 FUNCTION DOES NOT EXIST The method used does not exist.
2 NO DATA No data has been received with the request.
3 INVALID API KEY Provided apikey is invalid.
4 NO CHECKER ID checker_id was missing.
5 INVALID CHECKER ID checker_id hasn't been recognized (no checker exists for the given checker_id).
6 INVALID REPORT ID report_id hasn't been recognized (no report exists for the given report_id).
7 REQUEST LIMIT EXCEEDED You exceeded the limit of API requests per minute, see "Usage" above.

Example error response

{ "STATUS":"ERROR", "ERRNO":"3", "ERRTXT":"INVALID API KEY" }

Creating a checker

URL/Endpoint:

http://api.yourbrowser.is/create_checker

Request Parameters

Parameter Name Description
apikey Your API key. Obligatory.
checker_id Your custom checker ID. It will be included in the returned checker URL. Obligatory.
checks An array of checks (detections) that you'd like to be included in the checker, in an order that they should be displayed in. See "Checks" below for details. Obligatory.
check_parameters See "Check Parameters" below for details.
ask If you want the checker to get user consent* before recording his browsing environment's data ("1") or to record the data immediately upon loading ("0"). Default value: "0".
redirect_url URL where you'd like to redirect the user after recording their browsing environment's data.
frame_url URL to be displayed instead of a checker page. The checker page is loaded in an invisible frame. When set, the "ask" parameter is overridden to "0".
callback URL where you'd like to receive information (checker_id and report_id via POST) when a new report for a given check is recorded.
language Language version of the checker page. If not set, the page will display in the detected language or in English in case of a not supported language.
Currently supported languages: "en", "es", "fr", "de", "pl", "da", "ja", "zh".

* In the European Union (EU), asking for user consent is required by Privacy Regulations.

Checks

Below listed detections can be included in your checker:

Check Name Description
browser Browser name & version.
operating_system Operating system name & version.
mobile_device Mobile device name.
screen_resolution User screen resolution.
current_viewport User current viewport size (browser window inner size).
pixel_ratio Current scale the web is displayed at.
color_depth Number of available colors.
javascript JavaScript availability.
java Java availability & version.
flash Flash availability & version.
silverlight Silverlight availability & version.
cookies Cookie files availability.
ip_address User IP address.
geolocation User country, city and GPS coordinates.
language User browser language.
time_zone User time zone.
twitter_login User Twitter login status.
facebook_login User Facebook login status. Doesn't work with custom domain.
googleplus_login User Google+ login status.
google_login User Google Account login status.
ad_blockers Ad blockers status.
connection_speed Internet download and upload speed at user's side. Not available when frame_url is set. Requires additional Parameters, see below.
image_text Informational box to be displayed on your checker page. Can include text and an image in the background. Not available when frame_url is set. Requires additional Parameters, see below.
feedback_textfield A form box to collect user feedback with a single-line text field. Not available when frame_url is set. Requires additional Parameters, see below.
feedback_textarea A form box to collect user feedback with a multi-line text area field. Not available when frame_url is set. Requires additional Parameters, see below.
feedback_dropdown A form box to collect user feedback with a drop-down field. Not available when frame_url is set. Requires additional Parameters, see below.
Check Parameters

Some checks require additional parameters:

Check Name Parameter Name Values
connection_speed speed_test_remote Indication of whether connection speed should be measured from yourbrowser.is server ("0") or your server ("1", speed_test_server required). Default value: "0".
speed_test_server URL of the connection speed test files located on your server (for speed_test_remote="1").
image_text label The text to be displayed.
image_url URL of the image to be displayed in the background, recommended dimensions: 250x250px.
feedback_textfield field_name Name for the field.
field_label Caption to be displayed above the field.
feedback_textarea field_name Name for the field.
field_label Caption to be displayed above the field.
feedback_dropdown field_name Name for the field.
field_label Caption to be displayed above the field.
values Available values, separated with ";", e.g. "Option 1;Option 2;Option 3".
multiple If multiple selection should be available - "0" (no) or "1" (yes). Default value: "0".

Sample Requests

{ "apikey":"3q64v4u6vyu37a3fg", "checker_id":"mychecker427", "checks":[ "operating_system", "browser" ] }


{ "apikey":"3q64v4u6vyu37a3fg", "checker_id":"mychecker428", "checks":[ "operating_system", "browser", "connection_speed", "image_text", "feedback_textfield", "feedback_dropdown" ], "check_parameters":{ "connection_speed":{ "speed_test_remote":"1", "speed_test_server":"http://www.mywebsite.com/speedtest/index.html" }, "image_text":{ "label":"We need to check your browser details to successfully provide support.", "image_url":"http://www.mywebsite.com/image.png" }, "feedback_textfield":{ "field_name":"user-tries", "field_label":"How many times did you try?" }, "feedback_dropdown":{ "field_name":"user-problems", "field_label":"How frequently did the problem occur?", "values":"only once;a few times;many times;every time I tried", "multiple":"0" } }, "headers":"1", "ask":"1", "callback":"http://www.mywebsite.com/my-callback-url", "language":"en" }

Response

After successfully creating or updating a checker, a status and the checker URL are returned.
This URL should be forwarded to the end user with a request to open it (and to confirm if "ask" has been set to "1").

Sample Responses

{ "STATUS":"CREATED", "URL":"http://mybrand.yourbrowser.is/mychecker427" }


{ "STATUS":"UPDATED", "URL":"http://mybrand.yourbrowser.is/mychecker427" }

Getting a list of reports

URL/Endpoint:

http://api.yourbrowser.is/get_reports

Request Parameters

Parameter Name Description
apikey Your API key. Obligatory.
checker_id ID of the checker used at the time of creation (see "Creating a checker" above). Obligatory.

Sample Request

{ "apikey":"3q64v4u6vyu37a3fg", "checker_id":"mychecker427" }

Response

This method will return a list of reports recorded by a specific checker.

Properties

Property Description
STATUS Response status - see "Statuses" above.
CHECKER Checker ID.
REPORTS A list of reports in the form of an array. See below for variables returned for every report.
Report variables
Variable Description
report_id Unique ID of the report.
created Date and time at which the report was recorded, "YYYY-MM-DD HH:MM:SS", UTC/GMT.
ip IP address of the user that generated the report.

Sample Responses

{ "STATUS":"OK", "CHECKER":" mychecker427", "REPORTS":[ ] }


{ "STATUS":"OK", "CHECKER":"mychecker427", "REPORTS":[ { "report_id":"576a369aa19dd13", "created":"2016-06-22 6:56:26", "ip":"89.70.52.182" }, { "report_id":"576a3c6092f3d14", "created":"2016-06-22 7:21:04", "ip":"89.70.52.182" }, { "report_id":"576a43daf320815", "created":"2016-06-22 7:52:58", "ip":"89.70.52.182" } ] }

Retrieving report details

URL/Endpoint:

http://api.yourbrowser.is/get_report

Request Parameters

Parameter Name Description
apikey Your API key. Obligatory.
checker_id ID of the checker used at the time of creation (see "Creating a checker" above). Obligatory.
report_id ID of the report, obtained from the report list (see "Getting a list of reports" above). Obligatory.
headers Indication of whether full HTTP headers should be included in the report ("1") or not ("0"). Default value: "0".

Sample Request

{ "apikey":"3q64v4u6vyu37a3fg", "checker_id":"mychecker427", "report_id":"576a369aa19dd13" }

Response

This method will return all recorded user details in a single report.

Properties

Property Description
STATUS Response status - see "Statuses" above.
CHECKER Checker ID.
REPORT Report ID.
CHECKS An array of all checks included in the checker along with values. See below for possible values that can be returned by particular checks.

Possible Check Values

Check Name Possible Values
http_header Full HTTP headers received from user's browser, base64-encoded.
browser Browser name & version.
operating_system Operating system name & version.
mobile_device Mobile device name.
screen_resolution Screen resolution (depending upon pixel ratio), width x height in pixels.
current_viewport Window inner size, width x height in pixels.
pixel_ratio Pixel ratio.
color_depth Number of colors.
javascript "1" (available) or "0" (not available).
java Version number or "0" (not available).
flash Version number or "0" (not available).
silverlight Version number or "0" (not available).
cookies "1" (available) or "0" (not available).
ip_address IP address.
geolocation Country & city, GPS latitude and GPS longitude, separated by ";".
language Language.
time_zone Time zone, accordingly to GMT.
twitter_login "1" (user logged in) or "0" (user not logged in).
facebook_login "1" (user logged in) or "0" (user not logged in).
googleplus_login "1" (user logged in) or "0" (user not logged in).
google_login "1" (user logged in) or "0" (user not logged in).
ad_blockers "1" (ad blocker active) or "0" (ad blocker not active).
connection_speed Download and upload speed in Mb/s, separated by ";".
image_text Not a real check, just an informational box that can contain text and an image.
feedback_textfield Text string entered by the user into the text field.
feedback_textarea Text string entered by the user into the textarea field.
feedback_dropdown Option(s) selected by the user in the drop-down field, separated with comma.

Sample response

{ "STATUS":"OK", "CHECKER":"mychecker428", "REPORT":"577660af084c243", "CHECKS":[ { "check":"http_header", "value":"PEhUVFBfQUNDRVBUPnRleHQvaHRtbCxhcHBsaWNhdGlvbi94aHRtbCt4bWwsYXBwbGljYXRpb24veG1sO3E9MC45LCovKjtxPTAuODwvSFRUUF9BQ0NFUFQ+PEhUVFBfQUNDRVBUX0VOQ09ESU5HPmd6aXAsIGRlZmxhdGU8L0hUVFBfQUNDRVBUX0VOQ09ESU5HPjxIVFRQX0FDQ0VQVF9MQU5HVUFHRT5wbCxlbi1VUztxPTAuNyxlbjtxPTAuMzwvSFRUUF9BQ0NFUFRfTEFOR1VBR0U+PEhUVFBfQ09OTkVDVElPTj5rZWVwLWFsaXZlPC9IVFRQX0NPTk5FQ1RJT04+PEhUVFBfQ09PS0lFPl9fdXRtYT02NjA0NjAyLjIwMzU3MjM0OTQuMTQ2MzEzODE3NS4xNDY3MjMxMzU2LjE0NjcyODc4MjQuMzc7IF9fdXRtej02NjA0NjAyLjE0NjU5ODAxOTUuMjIuMy51dG1jc3I9eWJyLmlzfHV0bWNjbj1yZWRpcmVjdGlvbnx1dG1jbWQ9cmVkaXJlY3Rpb247IF9fdXRtYT05NzgwMDg2MS4xMzkzODc1MjA3LjE0NjM3NzEyNTAuMTQ2NzI4ODEyMS4xNDY3Mzc0NTg5LjI1OyBfX3V0bXo9OTc4MDA4NjEuMTQ2Mzc3MTI1MC4xLjEudXRtY3NyPShkaXJlY3QpfHV0bWNjbj0oZGlyZWN0KXx1dG1jbWQ9KG5vbmUpOyByZWZlcj1odHRwJTNBJTJGJTJGc2l0cHJvLnlvdXJicm93c2VyLmlzJTJGa2M4XzA0OyB5b3VyYnJvd3Nlcj01dnYwbHR0MmJ1YWg2bnIxbWtlMWhtOXFpMjsgX191dG1iPTk3ODAwODYxLjEuMTAuMTQ2NzM3NDU4OTsgX191dG1jPTk3ODAwODYxPC9IVFRQX0NPT0tJRT48SFRUUF9IT1NUPnNpdHByby55b3VyYnJvd3Nlci5pczwvSFRUUF9IT1NUPjxIVFRQX1VTRVJfQUdFTlQ+TW96aWxsYS81LjAgKFdpbmRvd3MgTlQgNi4zOyBXT1c2NDsgcnY6NDcuMCkgR2Vja28vMjAxMDAxMDEgRmlyZWZveC80Ny4wPC9IVFRQX1VTRVJfQUdFTlQ+" }, { "check":"browser", "value":"Firefox 47.0" }, { "check":"operating_system", "value":"Windows 8.1" }, { "check":"screen_resolution", "value":"1536x864" }, { "check":"current_viewport", "value":"1519x710" }, { "check":"pixel_ratio", "value":"1.25:1" }, { "check":"color_depth", "value":"24 bit" }, { "check":"javascript", "value":"1" }, { "check":"java", "value":"Version 1.8.0_91" }, { "check":"flash", "value":"Version 22.0" }, { "check":"silverlight", "value":"0" }, { "check":"cookies", "value":"1" }, { "check":"ip_address", "value":"89.70.52.182" }, { "check":"geolocation", "value":"Poland,Katowice;50.2584;19.0275" }, { "check":"language", "value":"Polish" }, { "check":"time_zone", "value":"GMT+02:00" }, { "check":"twitter_login", "value":"1" }, { "check":"facebook_login", "value":"1" }, { "check":"googleplus_login", "value":"0" }, { "check":"google_login", "value":"1" }, { "check":"ad_blockers", "value":"0" }, { "check":"connection_speed", "value":"23.70;17.17" }, { "check":"feedback_textfield", "value":"lorem ipsum dolor" }, { "check":"feedback_textarea", "value":"lorem ipsum dolor\nsit amet" }, { "check":"feedback_dropdown", "value":"Option 1,Option 3" } ] }

Changelog

Version 1.1 - "language" request parameter added to create_checker.

Welcome Product Hunter! If you decide to try out the API, the first month is on us! Just let us know.