OAuth Authorization Model

Yahoo! Search BOSS Geo uses OAuth as a simple and secure method for validation and access. It’s an open authorization model based primarily on existing standards that ensures secure credentials can be provisioned and verified by different software platforms. For detailed information on Yahoo!’s implementation of the OAuth standard, see the documentation OAuth Authorization Model on the Yahoo! Developer Network.

Using OAuth with BOSS Geo

OAuth allows you and visitors to your web page, to securely access the Yahoo! Geo content. OAuth provides secure access to this content by using your BOSS application ID and the Yahoo! API key to verify your account, access privileges, and allow for correct billing from Yahoo!


Authentication for BOSS Geo queries requires OAuth information in the HTTP header OR through parameters in the GET request. There are six elements that are required for authorization:

  1. oauth_version=1.0 – The standard of OAuth supported by BOSS Geo.
  2. oauth_timestamp= – The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value MUST be a positive integer and MUST be equal to or greater than the timestamp used in previous requests. The timestamp can be reused for up to 5 minutes. Important: After 5 minutes a fresh timestamp must be supplied.
  3. oauth_nonce – is a random string, uniquely generated for all requests for a specific timestamp. This helps verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel (such as HTTP).
  4. oauth_consumer_key= – obtained from YDN during the BOSS project registration process. This is unique to the developer. Please follow the directions on the displayed key page and copy the entire key from YDN. If you do not copy the entire key, this results in a “Consumer Key rejected” error.
  5. oauth_signature_method=HMAC-SHA1 – (specific algorithm used for BOSS OAuth calls).
  6. oauth_signature – can be generated by an OAuth library. A list of supported OAuth libraries is available here: http://oauth.net/code. Over a dozen languages are supported.

Example of using OAuth in HTTP Header:

Authorization: OAuth


Using OAuth with GET parameters:

Add key="value" from the authorization header into GET parameters as &key=value in line with the other API parameters.

OAuth Coding Examples

The following sections provide quick start examples of using OAuth in various common programming languages. BOSS is providing this information to help you get up and running quickly with your BOSS Geo implementations. Below are some self-serve samples that have been contributed by the BOSS User Community.


Please make sure to insert the correct value for “ADD YOUR KEY HERE” and “ADD YOUR SECRET HERE” in the appropriate places in the code examples below.


All code samples below are adapted from original contributions. Contributors are noted.

PHP Example

  1. Sign up for OAuth application through http://developer.yahoo.com.
  2. Download the PHP OAuth Library from http://oauth.net/code. This is where you can retrieve the required OAuth.php file displayed below.
  3. Create a php script based on this example updating the $cc_key with your Consumer Key and the $cc_secret with your Consumer Secret:

PlaceFinder Example

These example code snipets are presented here for your use in your code. You can copy and paste from this section. Remember to change the key values, parameters, and any variables to make this snippet work with your BOSS Geo implementations.


$url = "https://yboss.yahooapis.com/geo/placefinder";

$args = array();
$args["q"] = "701+first+avenue+sunnnyvale";

$consumer = new OAuthConsumer($cc_key, $cc_secret);
$request = OAuthRequest::from_consumer_and_token($consumer, NULL,"GET", $url,
$request->sign_request(new OAuthSignatureMethod_HMAC_SHA1(), $consumer, NULL);

$url = sprintf("%s?%s", $url, OAuthUtil::build_http_query($args));
$ch = curl_init();
$headers = array($request->to_header());
curl_setopt($ch,CURLOPT_ENCODING , "gzip");
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

print_r("Request Headers\n");

$rsp = curl_exec($ch);

print_r("\nHere is the XML response for Placefinder\n");


PlaceSpotter Example

These example code snipets are presented here for your use in your code. You can copy and paste from this section. Remember to change the key values, parameters, and any variables to make this snippet work with your BOSS Geo implementations.


$url = "https://yboss.yahooapis.com/geo/placespotter";


$text = "EYES ON LONDON Electric night in 100-meter dash
LONDON (AP) — Around the 2012 Olympics and its host city with journalists from
The Associated Press bringing the flavor and details of the games to you:
The fastest men in the world on one of the fastest tracks around. Should make
for an electric night in the 100-meter dash.
Usain Bolt, Yohan Blake and the rest of a blazing will run in the semifinals,
with the fastest advancing to the finals on Sunday night.
Bolt was just OK in the preliminaries on Saturday, starting poorly on his way
to a 10.09. That's good for sixth fastest, but the world record holder says he
feels great heading into the big day. Americans Ryan Bailey and Justin Gatlin
are also in the mix.";

$args = array();

$args["documentType"] = urlencode("text/plain");
$args["documentContent"] = urlencode($text);

$consumer = new OAuthConsumer($cc_key, $cc_secret);
$request = OAuthRequest::from_consumer_and_token($consumer, NULL,"POST", $url,
$request->sign_request(new OAuthSignatureMethod_HMAC_SHA1(), $consumer, NULL);
$url = sprintf("%s?%s", $url, OAuthUtil::build_http_query($args));
$ch = curl_init();
$headers = array($request->to_header());
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$rsp = curl_exec($ch);

Perl Example

use strict;
use lib 'extra_mods';
use lib 'extra_mods/5.8';
use JSON;
use Net::OAuth;
use LWP::UserAgent;
use Data::Dumper;


my $expected_result_format = 'xml'; #xml or json

my %args;
$args{q} = "701+first+avenue+sunnnyvale"; # This is the query we are searching for
$args{format} = $expected_result_format;
$args{count} = 1; # number of results to be returned

my $buckets = "placefinder"; # placefinder, placespotter(BOSS Geo services)

print get_response(\%args,$buckets);

sub get_response {
    my %args = %{(shift)};
    my $buckets = shift;

    my $ua = LWP::UserAgent->new;

    my $cc_key = "";

    my $cc_secret = "";

    # Source Url
    my $url = "https://yboss.yahooapis.com/geo/$buckets";

    # Create request
    my $request = Net::OAuth->request("request token")->new(
            consumer_key => $cc_key,
            consumer_secret => $cc_secret,
            request_url => $url,
            request_method => 'GET',
            signature_method => 'HMAC-SHA1',
            timestamp => time,
            nonce => 'hsu94j3884jdopsl',
            callback => 'http://printer.example.com/request_token_ready',
            extra_params => \%args

    # Sign request

    # Get message to the Service Provider
    my $res = $ua->get($request->to_url);

    # If request is success, display content
        if ($res->is_success) {
            return $res->content;
        else {
        # Print error and die
                        Dumper $res;
            die "Something went wrong";


Perl 5.8+

Location: http://www.perl.org/get.html

extra mods:




* Specific CPAN Modules are required. Please see the code for required modules.

Ruby Example

Example: example.rb

require 'oauth_util.rb'
require 'net/https'

def get_response(args,buckets)
    url = "https://yboss.yahooapis.com/geo/"+buckets+"?"
    arg_count = 0
    args.each do|key,value|
        url = url + key + "=" + value+"&"

    if(arg_count > 0)

    parsed_url = URI.parse( url )

    o = OauthUtil.new
    o.consumer_key = "ADD YOUR KEY HERE"
    o.consumer_secret = "ADD YOUR SECRET HERE"

    http = Net::HTTP.new(parsed_url.host, 443)
    http.use_ssl = true
    http.start do | http |
        req = Net::HTTP::Get.new "#{ parsed_url.path }?#{ o.sign(parsed_url).query_string }"
        response = http.request(req)
        return response.read_body

args = Hash.new
args["format"] = "xml"
#args["format"] = "json"
args["q"] = "watch1"
args["count"] = "1"

buckets = "placefinder"

print get_response(args,buckets)



Location: https://gist.github.com/383159

License: https://gist.github.com/375593

C# Example

Example: boss_test.cs

using System;
using System.Net;
using OAuth;

namespace ConsoleApplication1{
class Program{
static void Main(string[] args){
string consumerKey = "...";
string consumerSecret = "...";
var uri = new Uri("https://yboss.yahooapis.com/geo/placefinder?callback=json2&q=701+first+avenue+sunnnyvale");
string url, param;
var oAuth = new OAuthBase();
var nonce = oAuth.GenerateNonce();
var timeStamp = oAuth.GenerateTimeStamp();
var signature = oAuth.GenerateSignature(uri, consumerKey,
consumerSecret, string.Empty, string.Empty, "GET", timeStamp, nonce,
OAuthBase.SignatureTypes.HMACSHA1, out url, out param);

using (WebRequest.Create(string.Format("{0}?{1}&oauth_signature={2}",
url, param, signature)).GetResponse()) { }


Location: http://oauth.googlecode.com/svn/code/csharp/OAuthBase.cs

License: Unknown

Contributor: Bryan Meverovich

Java Example

Example: SignPostTest.java

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.net.URLEncoder;

import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Logger;

import oauth.signpost.OAuthConsumer;
import oauth.signpost.basic.DefaultOAuthConsumer;

 * Sample code to use Yahoo! Search BOSS
 * Please include the following libraries
 * 1. Apache Log4j
 * 2. oAuth Signpost
 * @author xyz
public class SignPostTest {

private static final Logger log = Logger.getLogger(SignPostTest.class);

protected static String yahooServer = "https://yboss.yahooapis.com/geo/";

// Please provide your consumer key here
private static String consumer_key = "";

// Please provide your consumer secret here
private static String consumer_secret = "";

/** The HTTP request object used for the connection */
private static StHttpsRequest httpRequest = new StHttpsRequest();

/** Encode Format */
private static final String ENCODE_FORMAT = "UTF-8";

/** Call Type */
private static final String callType = "placefinder";

private static final int HTTP_STATUS_OK = 200;

 * @return
public int returnHttpsData()
throws UnsupportedEncodingException,

if(this.isConsumerKeyExists() && this.isConsumerSecretExists()) {

// Start with call Type
String params = callType;

// Add query
params = params.concat("?q=");

// Encode Query string before concatenating
params = params.concat(URLEncoder.encode(this.getSearchString(), "UTF-8"));

// Create final URL
String url = yahooServer + params;

// Create oAuth Consumer
OAuthConsumer consumer = new DefaultOAuthConsumer(consumer_key, consumer_secret);

// Set the HTTP request correctly

try {
log.info("sending get request to" + URLDecoder.decode(url, ENCODE_FORMAT));
int responseCode = httpRequest.sendGetRequest(url);

// Send the request
if(responseCode == HTTP_STATUS_OK) {
log.info("Response ");
} else {
log.error("Error in response due to status code = " + responseCode);

} catch(UnsupportedEncodingException e) {
log.error("Encoding/Decording error");
} catch (IOException e) {
log.error("Error with HTTP IO", e);
} catch (Exception e) {
log.error(httpRequest.getResponseBody(), e);
return 0;

} else {
log.error("Key/Secret does not exist");
return 1;

private String getSearchString() {
return "701+first+avenue+sunnyvale";

private boolean isConsumerKeyExists() {
if(consumer_key.isEmpty()) {
log.error("Consumer Key is missing. Please provide the key");
return false;
return true;

private boolean isConsumerSecretExists() {
if(consumer_secret.isEmpty()) {
log.error("Consumer Secret is missing. Please provide the key");
return false;
return true;
 * @param args
public static void main(String[] args) {


try {

SignPostTest signPostTest = new SignPostTest();


} catch (Exception e) {
log.info("Error", e);


Example: StHTTPRequest.java

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpsURLConnection;
import java.net.MalformedURLException;
import java.net.URL;

import org.apache.log4j.Logger;

import oauth.signpost.OAuthConsumer;
import oauth.signpost.exception.OAuthCommunicationException;
import oauth.signpost.exception.OAuthExpectationFailedException;
import oauth.signpost.exception.OAuthMessageSignerException;

 * @author David Hardtke
 * @author xyz
 * Simple HTTP Request implementation
public class StHttpsRequest {

private static final Logger log = Logger.getLogger(StHttpRequest.class);

    private String responseBody = "";

    private OAuthConsumer consumer = null;

    /** Default Constructor */
    public StHttpRequest() { }

    public StHttpRequest(OAuthConsumer consumer) {
        this.consumer = consumer;

    public HttpsURLConnection getConnection(String url)
    throws IOException,
     try {
             URL u = new URL(url);

             HttpsURLConnection uc = (HttpsURLConnection) u.openConnection();

             if (consumer != null) {
                 try {
                     log.info("Signing the oAuth consumer");

                 } catch (OAuthMessageSignerException e) {
                     log.error("Error signing the consumer", e);
                     throw e;

                 } catch (OAuthExpectationFailedException e) {
                 log.error("Error signing the consumer", e);
                 throw e;

                 } catch (OAuthCommunicationException e) {
                 log.error("Error signing the consumer", e);
                 throw e;
             return uc;
     } catch (IOException e) {
     log.error("Error signing the consumer", e);
     throw e;

     * Sends an HTTP GET request to a url
     * @param url the url
     * @return - HTTP response code
    public int sendGetRequest(String url)
    throws IOException,
    OAuthCommunicationException {

        int responseCode = 500;
        try {
            HttpsURLConnection uc = getConnection(url);

            responseCode = uc.getResponseCode();

            if(200 == responseCode || 401 == responseCode || 404 == responseCode){
                BufferedReader rd = new BufferedReader(new InputStreamReader(responseCode==200?uc.getInputStream():uc.getErrorStream()));
                StringBuffer sb = new StringBuffer();
                String line;
                while ((line = rd.readLine()) != null) {
         } catch (MalformedURLException ex) {
            throw new IOException( url + " is not valid");
        } catch (IOException ie) {
            throw new IOException("IO Exception " + ie.getMessage());
        return responseCode;

     * Return the Response body
     * @return String
    public String getResponseBody() {
        return responseBody;

     * Setter
     * @param responseBody
    public void setResponseBody(String responseBody) {
        if (null != responseBody) {
            this.responseBody = responseBody;

     * Set the oAuth consumer
     * @param consumer
    public void setOAuthConsumer(OAuthConsumer consumer) {
        this.consumer = consumer;



Location: http://code.google.com/p/oauth-signpost/

License: http://www.apache.org/licenses/LICENSE-2.0

Contributor: David Hardtke

Apache Logger

Location: http://logging.apache.org/log4j/1.2/download.html

License: http://logging.apache.org/log4j/1.2/license.html

Node.JS Example

Example: Node.JS

function yahooSearch(consumerKey, consumerSecret, query, count,
 var geoSearchUrl = 'https://yboss.yahooapis.com/geo/placefinder';

  var finalUrl = geoSearchUrl + '?' + qs.stringify({
    q: query,  //geocode query keyword
    flags: 'J',
    count: count,

  var oa = new OAuth(webSearchUrl, geoSearchUrl , consumerKey, consumerSecret, "1.0", null, "HMAC-SHA1");
  oa.setClientOptions({ requestTokenHttpMethod: 'GET' });
  oa.getProtectedResource(finalUrl, "GET", '','', callback_error_data_response);

// Use this function to make a call back. Make sure to provide the right key, secret and query for this to work correctly yahooSearch('YAHOO CONSUMER KEY GOES HERE', 'YAHOO CONSUMER SECRET GOES HERE', 'GEOCODE ADDRESS', 10, function(error, data, response){
// enter some code here and access the results from the "data" variable in JSON format

BOSS Geo Node.JS Library

Location: - Mikel Cavia has put together a library to use BOSS Geo using Node.JS. Learn more on github.

Contributor: Heber Allred (edited by BOSS Team) and Mikel Cavia