All rights reserved © yourbrowser.is.
Terms & Conditions, Privacy Policy
Blog, Browser Market Share
Tweet about us, Share us on Facebook or LinkedIn
All the names and logos have been used only for information purposes and can be registered trademarks of their owners.
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:
- Create a checker.
- Send its URL to the user with a request to open it.
- Get a list of reports collected by the checker.
- 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.
https://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:
https://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. |
| facebook_login | User Facebook login status. Doesn't work with custom domain. |
| 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":"https://mybrand.yourbrowser.is/mychecker427"
}
{
"STATUS":"UPDATED",
"URL":"https://mybrand.yourbrowser.is/mychecker427"
}
Getting a list of reports
URL/Endpoint:
https://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:
https://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. |
| facebook_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":"facebook_login",
"value":"1"
},
{
"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.