Pulling Bright Local API Data into my Ruby on Rails App - API Docs written in PHP

Question

I'm trying to build a rails app that pulls data from several different SEO tool API's. For Bright Local (see their API docs here - http://apidocs.brightlocal.com/ ) all the API doc examples are written in PHP, which I can't read all that great.

So first, to ask a specific question, how would I write this batch request in Ruby:

<?php
use BrightLocal\Api;
use BrightLocal\Batches\V4 as BatchApi;

$api = new Api('[INSERT_API_KEY]', '[INSERT_API_SECRET]');
$batchApi = new BatchApi($api);
$result = $batchApi->create();
if ($result['success']) {
    $batchId = $result['batch-id'];
}

Also, any suggestions for how I can bring myself up to snuff on using API's in my rails apps?

Answer 1

Our docs do currently only show PHP examples - although we are planning to expand on that and Ruby is one of the languages we'll be looking to add.

A simple command line CURL request for the above PHP code would look like this:

curl --data "api-key=<YOUR API KEY HERE>" https://tools.brightlocal.com/seo-tools/api/v4/batch

and would return a response like this:

{"success":true,"batch-id":<RETURNED BATCH ID>}

All our API endpoints respond to either POST, PUT, GET or DELETE. It's also important to note that whenever data is posted with POST or PUT it's passed like "param1=value1&param2=value2" in the body of the request rather than JSON encoded.

I don't know Ruby at all I'm afraid but something like this might make the request you want:

params = {"api-key" => "<YOUR API KEY>"}
Net::HTTP::Post.new("https://tools.brightlocal.com/seo-tools/api/v4/batch").set_form_data(params)

Answer 2

I'm also implementing brightlocal into my Rails app. I'm using the HTTParty gem. this is what I have so far and am able to make successful calls

this is to obtain your batch id:

api_key = YOUR_API_KEY
secret_key = YOUR_SECRET_KEY


request_url = "https://tools.brightlocal.com/seo-tools/api/v4/batch?api-key=#{api_key}"
response = HTTParty.post(request_url)

if response.code == 201
  batch_id = response['batch-id']
end

this is an example of running one job in the batch (the query parameters go inside the body):

rank_url = "https://tools.brightlocal.com/seo-tools/api/v4/rankings/search"

response = HTTParty.post(rank_url, {
                  :body => {
                      "api-key" => api_key,
                      "batch-id" => batch_id,
                      "search-engine" => "google",
                      "country" => "USA",
                      "search-term" => "restaurant"
                    }
                })

I have not tested this next part, but theoretically, this is how you would deal with signatures and expirations

expires = Time.now.to_i + 1800
string_to_sign = "#{api_key}.#{expires}"
binary_signature = OpenSSL::HMAC.digest('sha1', string_to_sign, secret_key)
url_safe_signature = CGI::escape(Base64.encode64(binary_signature).chomp)

All that would be left is to use a PUT request to commit the batch, and a GET request to retrieve the data inside the batch.

EDIT: Figured out how to correctly get a passing signature for the jobs that require one. (this example is for local search rank checker http://apidocs.brightlocal.com/#local-search-rank-checker )

expires = Time.now.to_i + 1800
concat = api_key + expires.to_s
sig = OpenSSL::HMAC.digest('sha1', secret_key, concat)
sig = CGI::escape(Base64.encode64(sig).chomp)

local_rank = "https://tools.brightlocal.com/seo-tools/api/v2/lsrc/add?api-key=#{api_key}&sig=#{sig}&expires=#{expires}"

response = HTTParty.post(local_rank, {
                :body => {
                  "name" => "pizza hut",
                  "search-terms" => "restaurant"
                }
              })

Answer 3

Since you are using Ruby and not PHP you will have to implement everything yourself. The example you give shows the user of a PHP wrapper created by BrightLocal (and it seems they only have it in PHP).

Basically you will have to make calls to the endpoints yourself and manage the data yourself instead of using their wrapper.