This tutorial will take you through the steps to create your account, install the BCWS PHP command line client, and walk you through its use. This tool is helpful for making ad-hoc calls to the BCWS API as well as debugging the requests your programs make or even for low volume scripting.
BrightCloud Web Services uses the 2-legged OAuth standard to validate your identity whenever you issue a request. Authentication ensures that you don't get charged for operations you did not authorize.
Security always relies on a secret. For BCWS, your secret is your BCWS Secret Access Key. Do not reveal it to anyone even if a request appears to come from BrightCloud. BCWS pairs your BCWS Secret Access Key with your BCWS Access Key ID. You will include your BCWS Access Key ID and a HMAC-SHA1 computed signature using your BCWS Secret Access Key in all BCWS requests. BCWS verifies that the sender of the request knows both the BCWS Access Key ID and the corresponding BCWS Secret Access Key and is not violating any other security measures set forth in the OAuth standard. BCWS does not process requests where the BCWS Access Key ID and BCWS Secret Key do not match or any other violations occur (e.g. reusing nonce values or timestamps which are out of line).
In the following samples, you simply add your BCWS Access Key ID and BCWS Secret Key to the sample files. For more information about authentication, please visit the OAuth.net website and our OAuth Integration for BrightCloud Web Service.
In order to continue, you must have completed the following steps:
To install the PHP client, simply decompress it into a subdirectory of your choosing and change into that directory.
Be sure to check out our other sample programs and code in the developer section of our website as well.
The first thing to do is to retrieve a list of BrightCloud categories and their associated Category IDs. These Category IDs are returned instead of the Category Name in order to conserve space. Therefore, the first thing your application will want to do is to download the latest copy of our Cateogry IDs and build a map of Category IDs to Category Name vaules.
To see what the REST call looks like to make this request you can use the "-d" flag of the command line client to "dump" the GET request insetad of making the call to the BCWS server. You are going to make a GET request to the URL /rest/uris/categories.
% php cmdclient.php -k your_access_key_id_here -s your_secret_access_key_id_here -m GET -u http://thor.brightcloud.com/rest/uris/categories -d
GET /rest/uris/categories HTTP/1.0
HOST: thor.brightcloud.com
Connection: close
Authorization: OAuth realm="",oauth_version="1.0",oauth_nonce="b1c80a7890ee3df421b3ac730d44fb12",oauth_timestamp="1248102047",oauth_consumer_key="gIQBlKQx5cxCeSGoLtbHsQ",oauth_token="",oauth_signature_method="HMAC-SHA1",oauth_signature="YbHGSU20CPVEWXcNt9lyCUmgTnk%3D"
The first thing to notice is that the BCWS Access Key ID (following the "-k" parameter) and BCWS Secret Access Key ID (following the "-s" parameter) were both required to make this call. They were used to generate the oauth_consumer_key (which is your BCWS Access Key ID) and the oauth_signature value (which is computed with your BCWS Secret Access Key ID) you see at the end of the OAuth Authorization header.
To see what the REST response looks like, simply remove the "-d" flag at the end of the command line and issue the response to the BCWS server.
% php cmdclient.php -k your_access_key_id_here -s your_secret_access_key_id_here -m GET -u http://thor.brightcloud.com/rest/uris/categories
fHTTP/1.1 200 OK
Etag: "9900072dbd616bdfe2867f2cfdeb33d1"
Connection: close
Content-Type: application/xml; charset=utf-8
Date: Mon, 20 Jul 2009 15:01:32 GMT
Server: WEBrick/1.3.1 (Ruby/1.8.7/2008-08-11)
X-Runtime: 183
Content-Length: 7973
Cache-Control: private, max-age=0, must-revalidate
Set-Cookie: _bcws_session=BAh7BzoMdXNlcl9pZGkGOg9zZXNzaW9uX2lkIiUzYTEyZWMxMGQ4YTczZTRhYjRiNWUyZGViMWNhYjE3OQ%3D%3D--7b95c5741e696701acdbddf3919c703cac2d1254; path=/; HttpOnly
Regular Response
< ?BrightCloud version=bcap/1.1? >
< bcap >
< response >
< status >200< /status >
< statusmsg >OK< /statusmsg >
< categories >
< cat >
< catid >68< /catid >
< catname >Abortion< /catname >
< catgroup >Legal Liability< /catgroup >
< /cat >
< cat >
< catid >46< /catid >
< catname >Abortion- ProChoice< /catname >
< catgroup >Legal Liability< /catgroup >
< /cat >
< cat >
< catid >48< /catid >
< catname >Abortion- Pro Life< /catname >
< catgroup >Legal Liability< /catgroup >
< /cat >
.
.
.
< /categories >
< /response >
< /bcap >
You can see all of the various Category Name, Category ID, and even Category Group values we supply for your convenience. These Category Groups are only suggestions, you can organize or utilize the Categories in whatever means is most convenient or useful to you.
To see what the REST call looks like to request what categories BrightCloud thinks a particular URL is in, you can again use the "-d" flag of the command line client to "dump" the GET request insetad of making the call to the BCWS server. This time the GET request is made to /rest/uris/[url]. For example, /rest/uris/www.google.com. Note that you can supply the protocol (e.g. http or https) or not. If you choose not to, we assume you're asking about http.
% php cmdclient.php -k your_access_key_id_here -s your_secret_access_key_id_here -m GET -u http://thor.brightcloud.com/rest/uris/www.google.com -d
GET /rest/uris/www.google.com HTTP/1.0
HOST: thor.brightcloud.com
Connection: close
Authorization: OAuth realm="",oauth_version="1.0",oauth_nonce="b1c80a7890ee3df421b3ac730d44fb12",oauth_timestamp="1248102047",oauth_consumer_key="gIQBlKQx5cxCeSGoLtbHsQ",oauth_token="",oauth_signature_method="HMAC-SHA1",oauth_signature="YbHGSU20CPVEWXcNt9lyCUmgTnk%3D"
To see what the REST response looks like, remove the "-d" flag at the end of the command line and issue the response to the BCWS server.
% php cmdclient.php -k your_access_key_id_here -s your_secret_access_key_id_here -m GET -u http://thor.brightcloud.com/rest/uris/www.google.com
HTTP/1.1 200 OK
Etag: "9900072dbd616bdfe2867f2cfdeb33d1"
Connection: close
Content-Type: application/xml; charset=utf-8
Date: Mon, 20 Jul 2009 15:01:32 GMT
X-Runtime: 183
Content-Length: 7973
Cache-Control: private, max-age=0, must-revalidate
Set-Cookie: _bcws_session=BAh7BzoMdXNlcl9pZGkGOg9zZXNzaW9uX2lkIiUzYTEyZWMxMGQ4YTczZTRhYjRiNWUyZGViMWNhYjE3OQ%3D%3D--7b95c5741e696701acdbddf3919c703cac2d1254; path=/; HttpOnly
Regular Response
< bcap >
< seqnum >1< /seqnum >
< response >
< status >200< /status >
< statusmsg >OK< /statusmsg >
< uri >www.google.com< /uri >
< categories >
< cat >
< catid >50< /catid >
< conf >85< /conf >
< /cat >
< /categories >
< bcri >88< /bcri >
< a1cat >1< /a1cat >
< /response >
< /bcap >
You can see all of the various Category IDs and Confidence Scores (numbers between the conf tags) we supply for your convenience. The Confidence Scores are what you would think they are, the higher they are the more sure BrightCloud is that the URL belongs to that particular category. One important thing to note on Confidence Scores - they will not sum to 100! The likelihood that a URL belongs to Sports is totally independent with whether it belongs in Gambling or not. Therefore, a "sports betting" site should have a high Confidence Scores in both categories.
The PHP command line application is even more capable than this - you can make any of the calls documented in our BCWS REST API. You can use the application's help command to learn about all of it's degrees of flexibility. To make a different BCWS REST call, you can specify the necessary request method ("-m") such as POST or PUT and the corresponding resource URL ("-u") to make the call. The PHP command line application will then convert these actions and your API credentials into a properly formed BCWS call and return the response. This output can then be filtered or written to a file so that other scripts can processes it further.
Hopefully by now you're off the ground and your imagination is racing to figure out how you can best utilize this new wealth of information! Need some additional guidelines or want to learn more? Check out our additional articles.
If any part of this documentation is confusing or if you need additional help, please check out our forums or send us feedback. We created this for you to use, and want to make sure we're doing the best we can to provide you what you need to enable better applications!