Introduction
The BrightLocal API provides programmatic access to BrightLocal’s Local SEO Tools. The API provides a “REST” style interface and returns all data as a JSON encoded strings.
API Types
We have two types of API methods:
- Methods which retrieve raw data offering you complete flexibility to create your own solutions (marked with Batch)
- Methods which allow you to manipulate clients and reports stored within your BrightLocal control panel (marked with Account)
The first type requires you to submit your requests as part of a batch - a container which makes it easy to bundle up multiple requests and poll for all results. You can read more about batches below.
API URL
The base API URL is: https://tools.brightlocal.com/seo-tools/api
Authentication
Generating a signature:
<?php
define('API_KEY', '<INSERT_API_KEY>');
define('API_SECRET', '<INSERT_API_SECRET>');
$expires = (int) gmdate('U') + 1800; // not more than 1800 seconds
$sig = base64_encode(hash_hmac('sha1', API_KEY.$expires, API_SECRET, true));
echo urlencode($sig); // for get requests
echo $sig;
expiry=$((`date +%s`+1800)) # not more than 1800 seconds
sig=$(echo -n "<INSERT_API_KEY>$expiry" | openssl dgst -sha1 -binary -hmac "<INSERT_API_SECRET>" | base64)
private string api_key = "<INSERT_API_KEY>";
private string api_secret = "<INSERT_API_SECRET>";
DateTime date = DateTime.Now;
DateTime origin = new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc); // The seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
TimeSpan diff = date.ToUniversalTime() - origin; // Subtract the seconds since the Unix Epoch from today's date.
double expires = Math.Floor(diff.TotalSeconds + 1800); // Not more than 1800 seconds
var encoding = new System.Text.ASCIIEncoding();
byte[] keyByte = encoding.GetBytes(api_secret);
byte[] messageBytes = encoding.GetBytes(api_key + expires);
using (var hmacsha1 = new HMACSHA1(keyByte))
{
byte[] hashmessage = hmacsha1.ComputeHash(messageBytes);
var signature = Convert.ToBase64String(hashmessage);
}
All methods require a valid trial or production API key. Methods which manipulate or retrieve data in your account additionally require a signature. You ideally need to generate this signature for each request and set a short expiry time. For testing purposes you can chose to create a signature that will be valid for up to 30 minutes.
Authentication Errors
If there’s a problem with your API key, signature or expires one of the following errors will be returned:
Invalid API Key
Error responses:
{
"errors": {
"INVALID_API_KEY": "Invalid API key specified"
}
}
Signature Incorrect
{
"errors": {
"INVALID_API_KEY": "Signatures don't match"
}
}
In this situation your signature doesn’t match the one we generated for comparison. Most like there’s something wrong in the way you’re generating your signature. If passing the signature in the query string make sure you’ve URL encoded it before submitting.
Invalid Permissions
{
"errors": {
"INVALID_API_KEY": "API key doesn't has access to the specified api call"
}
}
If you see this error it means that your API key only has partial access to our API. You’ll need to contact us to get the API method you’re trying to call associated with your API key.
No Trial Requests Left
{
"errors": {
"INVALID_API_KEY": "No trial requests left"
}
}
Your trial key has used its allocation of free credits and you’re trying to call a batch API method that needs credits. Methods that manipulate your account don’t need credits or a production key.
API Key Doesn’t Support Signed Requests
{
"errors": {
"INVALID_API_KEY": "API key not upgraded to support signed requests"
}
}
Most likely you’ve got a very old API key and you’re trying to access one of our newer API methods that needs to be sent signature and expiry information but your key doesn’t have these.
Signature Too Old
{
"errors": {
"INVALID_API_KEY": "Signature expired too long ago"
}
}
The signature you’re trying to use expired more than 30 minutes ago. Ideally you should generate a new signature with every request but you must generate a new one at least every 30 minutes.
Signature Expiry Too Long
{
"errors": {
"INVALID_API_KEY": "Specified expiry is too far in the future (max 1800 seconds allowed)"
}
}
You can only generate a signature that expires a maximum of 30 minutes into the future. If you see this message you need to check the expiry value you’re using to generate your signature.
General Error Handling
{
"errors": {
"INVALID_COMPANY_NAME": "Company name not specified",
"INVALID_COMPANY_URL": "Company URL not specified",
"INVALID_COUNTRY": "Country ISO 3 code not specified",
"INVALID_BUSINESS_CATEGORY_ID": "Business category ID not specified"
}
}
When an error occurs the data returned contains an error section with a list of relevant errors. Errors are returned when incorrect parameters are passed to an API method and in a few other distinct cases.
Generally the response will contain a top level node errors {} when an error has occurred and response {} when a successful result is returned.
API Wrapper
If you work with PHP or C# we have API wrappers which simplify authentication against our API and provide simple methods for making requests.
The PHP and C# examples in this documentation use these wrappers.
- PHP - https://github.com/BrightLocal/apiclient-php or via Composer at https://packagist.org/packages/brightlocal/apiclient-php
- C# - https://github.com/BrightLocal/apiclient-csharp or via NuGet at https://www.nuget.org/packages/Brigthlocal.apiclient-csharp/2.0.0.15.
Batches
A batch acts like a container for API requests. It allows you to group requests for several types of data together and poll for results via a single consolidated call. All bar one of our raw data APIs need to be used within the context of a batch. The basic steps for using a batch are outlined below:
- Request a new batch ID
- Add one or more requests for data to the batch
- Commit the batch
- Poll for results
Create
Batch Method
Creating a batch
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
https://tools.brightlocal.com/seo-tools/api/v4/batch
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID '{0}'", batch.GetId());
Success - status code 201 Created
{
"success": true,
"batch-id": "17"
}
Failure
{
"success": false
}
Creates a new batch. You can add jobs to the batch to enable you to fetch different kinds of data.
A batch can have one of 5 states:
- Created - jobs can be added to the batch
- Committed - batch closed for further jobs, no jobs being processed yet
- Running - one or more jobs are being processed
- Stopped - one or more jobs in the batch failed
- Finished
Jobs within a batch can also have one of 5 states:
- Pending - added to batch but not queued for processing
- Queued - added to batch and queued for processing
- Processing - currently being processed by a worker
- Failed - processing failed
- Completed - processing completed successfully and job results are available
- Authentication for this method is via API key only.
Whilst you can technically add as many jobs as you want to a batch we recommend you submit jobs in batches of a few hundred at a time. This will allow you to start receiving results sooner.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/batch
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| stop-on-job-error | 1 or 0. default 0. If errors are found in one job the batch will be stopped and no further jobs will be processed. |
| callback | Callback URL. When a batch fails or completes the batch results will be posted to this callback URL |
| callback_request_format | Request format for callback URL. Available values: form, json. Default: form |
Commit Batch
Batch Method
Committing a batch
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$batchId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$batch = $api->getBatch($batchId);
$batch->commit();
printf('Committed batch successfully.%s', PHP_EOL);
curl -X PUT \
-d 'api-key=<INSERT_API_KEY>' \
-d 'batch-id=<INSERT_BATCH_ID>' \
https://tools.brightlocal.com/seo-tools/api/v4/batch
int batchId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.GetBatch(batchId);
batch.Commit();
Console.WriteLine("Batch committed successfully");
Success - status code 200 OK
{
"success":true
}
Failure - status code 400 Bad Request
{
"success": false,
"errors" : { "INVALID_JOBS_COUNT":"Batch can't be committed with no jobs" }
}
{
"success": false,
"errors" : { "BATCH_ALREADY_COMMITTED":"This batch has been committed already" }
}
Committing a batch signals that you’ve finished adding jobs. At this point our systems will start processing the jobs that you’ve added. Once you commit a batch no further jobs can be added to it.
Authentication for this method is via API key only.
HTTP Request
PUT https://tools.brightlocal.com/seo-tools/api/v4/batch
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
Get Results
Batch Method
Getting batch results
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$batchId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$batch = $api->getBatch($batchId);
print_r($batch->getResults());
curl 'https://tools.brightlocal.com/seo-tools/api/v4/batch?api-key=<INSERT_API_KEY>&batch-id=<INSERT_BATCH_ID>'
int batchId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.GetBatch(batchId);
Console.WriteLine(batch.GetResults());
Success - status code 200 OK
{
"success": true,
"status": "Finished",
"results": {
"LdFetchProfileUrl": [
{
"results": [
{
"url": "https://plus.google.com/117512971192208385977/about?hl=en&rfmt=s"
}
],
"status": "Completed",
"job-id": 318
}
],
"LdFetchProfileDetails": [
{
"results": [
{
"business_name": "Hub Plumbing & Mechanical",
"street_address": null,
"postcode": null,
"region": null,
"locality": null,
"address": "Greenwich Village New York, NY",
"contact_telephone": "+1 917-634-8888",
"description_present": true,
"num_photos": 2,
"star_rating": "4.7",
"num_reviews": 10,
"claimed": true,
"website_url": "http://www.hubplumbingnyc.com/",
"cid": "117512971192208385977",
"categories": "Plumber",
"check_in": null
}
],
"status": "Completed",
"job-id": 318
}
]
},
"statuses": {
"Completed": 2
}
}
This retrieves the results of all jobs added to the batch. Results are added as they’re returned so you can keep polling this endpoint to retrieve results progressively. Once results for all jobs have been returned the batch will be marked as “Finished”.
Authentication for this method is via API key only.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/batch
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
Delete
Batch Method
Delete a batch
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$batchId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$batch = $api->getBatch($batchId);
$batch->delete();
printf('Successfully deleted batch %d%s', $batchId, PHP_EOL);
curl -X DELETE 'https://tools.brightlocal.com/seo-tools/api/v4/batch?api-key=<INSERT_API_KEY>&batch-id=<INSERT_BATCH_ID>'
int batchId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.GetBatch(batchId);
batch.Delete();
Console.WriteLine("Batch deleted successfully");
Success - status code 200 Ok
{
"success": true
}
Failure - status code 404 Not Found
{
"success": false,
"errors" : { "INVALID_BATCH_ID": "Batch ID not found" }
}
Delete a batch. This also deletes all data retrieved for jobs added to the batch.
Authentication for this method is via API key only.
HTTP Request
DELETE https://tools.brightlocal.com/seo-tools/api/v4/batch
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
Stop Batch
Batch Method
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$batchId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$batch = $api->getBatch($batchId);
$batch->stop();
echo 'Successfully stopped batch' . PHP_EOL;
curl -X PUT
-d 'api-key=<INSERT_API_KEY>' \
-d 'batch-id=<INSERT_BATCH_ID>' \
https://tools.brightlocal.com/seo-tools/api/v4/batch/stop
int batchId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.GetBatch(batchId);
batch.Stop();
Console.WriteLine("Batch stoped successfully");
Success - status code 200 Ok
{
"success": true
}
Failure - status code 404 Not Found
{
"success": false,
"errors" : { "INVALID_BATCH_ID": "Batch ID not found" }
}
Cancels a batch midway through processing. Any jobs in the batch that haven’t already been processed will also be cancelled.
HTTP Request
PUT https://tools.brightlocal.com/seo-tools/api/v4/batch/stop
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
Rankings
Search (deprecated)
Batch Method
Fetch rankings
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
use BrightLocal\Exceptions\BatchAddJobException;
$directory = 'google';
// setup API wrapper
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step 1: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
// Step 2: Add directory jobs to batch
$searches = [
[
'search-engine' => $directory,
'country' => 'USA',
'google-location' => 'New York, NY',
'search-term' => 'restaurant new york',
'urls' => json_encode(['le-bernardin.com']),
'business-names' => json_encode(['Le Bernardin']),
], [
'search-engine' => $directory,
'country' => 'USA',
'google-location' => 'New York, NY',
'search-term' => 'restaurant manhattan',
'urls' => json_encode(['le-bernardin.com']),
'business-names' => json_encode(['Le Bernardin']),
], [
'search-engine' => $directory,
'country' => 'USA',
'google-location' => 'New York, NY',
'search-term' => 'restaurant 10019',
'urls' => json_encode(['le-bernardin.com']),
'business-names' => json_encode(['Le Bernardin'])
],
];
foreach ($searches as $search) {
try {
$response = $batch->addJob('/v4/rankings/search', $search);
printf('Added job with ID %d%s', $response->getResult()['job-id'], PHP_EOL);
} catch (BatchAddJobException $exception) {
printf('Error, job for directory "%s" not added. Message: %s%s', $directory, $exception->getMessage(), PHP_EOL);
}
}
// Commit batch (to indicate that all jobs have been added and that processing should start)
$batch->commit();
printf('Batch committed successfully, awaiting results.%s', PHP_EOL);
do {
sleep(5);
$response = $batch->getResults();
} while (!in_array($response->getResult()['status'], ['Stopped', 'Finished'], true));
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'batch-id=<INSERT_BATCH_ID>' \
-d 'search-engine=google' \
-d 'country=USA' \
-d 'google-location=new+york,ny' \
-d 'search-term=restaurant' \
-d 'urls=["jean-georgesrestaurant.com"]' \
-d 'business-names=["Jean-Georges Restaurant"]' \
https://tools.brightlocal.com/seo-tools/api/v4/rankings/search
List<Parameters> searches = new List<Parameters>
{
new Parameters
{
["search-engine"] = "google",
["country"] = "USA",
["google-location"] = "New York, NY",
["search-term"] = "restaurant new york" ,
["urls"] = new List<string> { "le-bernardin.com" } ,
["business-names"] = new List<string>() { "Le Bernardin" }
},
new Parameters
{
["search-engine"] = "google",
["country"] = "USA",
["google-location"] = "New York, NY",
["search-term"] = "restaurant manhattan",
["urls"] = new List<string> { "le-bernardin.com" },
["business-names"] = new List<string>() { "Le Bernardin" }
},
new Parameters
{
["search-engine"] = "google",
["country"] = "USA",
["google-location"] = "New York, NY",
["search-term"] = "restaurant 10019",
["urls"] = new List<string> { "le-bernardin.com" },
["business-names"] = new List<string>() { "Le Bernardin" }
}
};
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID {0}", batch.GetId());
foreach (Parameters parameters in searches)
{
try
{
// Add jobs to batch
dynamic jobResponse = batch.AddJob("/v4/rankings/search", parameters);
Console.WriteLine("Added job with ID {0}", jobResponse["job-id"]);
}
catch (GeneralException exception)
{
Console.WriteLine(exception.Message);
}
}
batch.Commit();
Console.WriteLine("Batch committed successfully, awaiting results.");
dynamic response;
do
{
Thread.Sleep(5000);
response = batch.GetResults();
} while (!(new List<string> { "Stopped", "Finished" }).Contains((string)response.status));
Console.WriteLine(response);
Success (201 Created)
{
"success": true,
"job-id": "1"
}
Failure (405 Method Not Allowed)
{
"success": false,
"errors": {
"INVALID_METHOD": "Invalid method specified. Only POST method is available"
}
}
Failure (500 Internal Server Error)
{
"success": false,
"reason": "Unable to add job"
}
Get Batch Rankings Result, Sucess(200 Ok)
{
"success": true,
"results": {
"SearchRankV2Api": [
{
"results": [
{
"identifier": "google",
"site": "Google Search",
"site-url": "http://www.google.com",
"search-url": "https://www.google.com/search?q=Back+Pain+midtown+manhattan&gl=us&gws_rd=cr&pws=0",
"search-term": "Back Pain midtown manhattan",
"results": [
{
"url": "http://thecenternyc.com/tag/back-pain/",
"orig_url": "http://www.thecenternyc.com/tag/back-pain/",
"title": "Back Pain Archives >> New York, NY 10001",
"ludocid": "",
"rank": 13,
"sub_rank": null,
"page": 2,
"type": "Organic",
"match": [
"website address"
],
"matched_url": "www.thecenternyc.com",
"serp-screenshot-url": "https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/6daa949323ef54687f41d95500751fd08256bc17.png"
},
{
"url": "http://thecenternyc.com/back-pain-nyc/",
"orig_url": "http://www.thecenternyc.com/back-pain-nyc/",
"title": "Back Pain NYC Archives >> The Center Chiropractic & PT NYC",
"ludocid": "",
"rank": 14,
"sub_rank": null,
"page": 2,
"type": "Organic",
"match": [
"website address"
],
"matched_url": "www.thecenternyc.com",
"serp-screenshot-url": "https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/6daa949323ef54687f41d95500751fd08256bc17.png"
}
],
"result-types": [
"Organic",
"Places",
"Carousel",
"Directory",
"Secondary"
],
"http-error": false,
"error-type": "None",
"serp-screenshots": [
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/6b3c2ea8060ad5d564bbbfb84e1dc877e401d7ab.png",
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/6daa949323ef54687f41d95500751fd08256bc17.png",
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/7e4fe6933ceff9303c541c3a4ff078d762aefff9.png",
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/fec74577c27321aa403da6733b82f3e3daa06407.png",
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/ceac0abca0233cb404f7859e8942ee1ed6851564.png"
]
}
],
"payload": {
"queue-attempts": 1,
"http-codes": [
0
],
"source": 3,
"api-key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"search-engine": "google",
"options": {
"urls": [
"www.thecenternyc.com"
],
"business-names": [
"The center for chiropractic & pt",
"the center for chiropractic decomperssion"
],
"search-term": "Back Pain midtown manhattan",
"postcode": "10001",
"telephone": "646-606-2580",
"country": "USA",
"google-location": "",
"bing-location": "",
"include-name-only-matches": true,
"num-search-pages": 5,
"debug": false,
"listings": false,
"screenshots-enabled": true,
"include-intermediate-html": false,
"append-location": false
},
"position": 0
},
"status": "Completed",
"job-id": 564270998
},
{
"results": [
{
"identifier": "google",
"site": "Google Search",
"site-url": "http://www.google.com",
"search-url": "https://www.google.com/search?q=apos+therapy+new+york&gl=us&gws_rd=cr&pws=0",
"search-term": "apos therapy new york",
"results": [
{
"url": "http://thecenternyc.com/apostherapy/",
"orig_url": "http://www.thecenternyc.com/apostherapy/",
"title": "Apostherapy NYC - Chiropractor NYC",
"ludocid": "",
"rank": 18,
"sub_rank": null,
"page": 2,
"type": "Organic",
"match": [
"website address"
],
"matched_url": "www.thecenternyc.com",
"serp-screenshot-url": "https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/9fce8698cbbfb59eeb4237dbb337c35e73fca0fa.png"
}
],
"result-types": [
"Organic",
"Places",
"Carousel",
"Directory",
"Secondary"
],
"http-error": false,
"error-type": "None",
"serp-screenshots": [
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/98aa8a19a602cefdb4d1ee0c2d220bf651b8d5cc.png",
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/9fce8698cbbfb59eeb4237dbb337c35e73fca0fa.png",
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/7346a7078076feaf155456e4437429bfc7e7bf94.png",
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/95b95e6189dc6a4cae2ec8247b53f507a6cf4925.png",
"https://seo-serp-screenshots.s3.amazonaws.com/2016/10/14/14/e6b467b76c9e2ea66c1ebfbdcd316ee95f97af6e.png"
]
}
],
"payload": {
"queue-attempts": 1,
"http-codes": [
0
],
"source": 3,
"api-key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"search-engine": "google",
"options": {
"urls": [
"www.thecenternyc.com"
],
"business-names": [
"The center for chiropractic & pt",
"the center for chiropractic decomperssion"
],
"search-term": "apos therapy new york",
"postcode": "10001",
"telephone": "646-606-2580",
"country": "USA",
"google-location": "",
"bing-location": "",
"include-name-only-matches": true,
"num-search-pages": 5,
"debug": false,
"listings": false,
"screenshots-enabled": true,
"include-intermediate-html": false,
"append-location": false
},
"position": 0
},
"status": "Completed",
"job-id": 564270999
}
]
},
"statuses": {
"Completed": 4
},
"status": "Finished"
}
This API method allows you to retrieve search ranking (and listing data) from the major search engines and their local variants, namely Google, Google Maps, Bing and Bing Maps. It works for the USA, United Kingdom, Canada and Australia.
This method needs to be used in conjunction with the batch methods described above.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/rankings/search
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
| search-engine | Required One of google, google-mobile, google-local, bing. |
| country | Required Determines which country specific variant of the specified search engine to use. As defined in “Supported Countries”(#supported-countries) table below. |
| google-location | Allows you to optionally localize results by specifying your physical location. Specify a ZIP, city name or region. Only applicable to US searches. Also see Geo Locations method. |
| bing-location | Allows you to optionally localize results by specifying your physical location. See Geo Locations method. |
| search-term | Required The search term to get ranking information for. |
| urls | The URLs to get ranking information for. Encode as a JSON string, e.g. [“www.bluehillfarm.com”, “www.candle79.com”, “shabutatsu.com”, “marea-nyc.com”, “www.taorestaurant.com”] (max 10). |
| business-names | A list of possible business names to search for. Encode as a JSON string, e.g. [“The Rose Pub”,“Rose Pub”,“The Rose”]. For backwards compatibility this also supports a newline (\n) separated list. |
| postcode | A valid ZIP or country postal code. |
| telephone | A valid telephone number. |
| include-secondary-matches | Determines whether or not to include results matched by name, telephone and/or ZIP/postal code. One of yes or no. This should be used in conjunction with the postal and telephone parameters. |
| listings | Include details of all SERPs returned, not just the matches. Defaults to “no”. Accepts “yes” or “no”. The default is “no”. |
| screenshots | Determines whether or not to generate SERP screenshots and include the links to those screenshots in the response. Accepts “yes” or “no”. The default is “no”. |
Bulk Search (deprecated)
Batch Method
Fetch rankings
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
use BrightLocal\Exceptions\BatchAddJobException;
$directory = 'google';
// setup API wrapper
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step 1: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
// Step 2: Add directory jobs to batch
$searches = [
'restaurant new york',
'restaurant manhattan',
'restaurant 10019',
];
try {
$response = $batch->addJob('/v4/rankings/bulk-search', [
'search-engine' => $directory,
'country' => 'USA',
'google-location' => 'New York, NY',
'search-terms' => json_encode($searches),
'urls' => json_encode(['le-bernardin.com']),
'business-names' => json_encode(['Le Bernardin'])
]);
printf('Added job with ID %d%s', $response->getResult()['job-id'], PHP_EOL);
} catch (BatchAddJobException $exception) {
printf('Error, job for directory "%s" not added. Message: %s%s', $directory, $exception->getMessage(), PHP_EOL);
}
// Commit batch (to indicate that all jobs have been added and that processing should start)
$batch->commit();
printf('Batch committed successfully, awaiting results.%s', PHP_EOL);
do {
sleep(5);
$response = $batch->getResults();
} while (!in_array($response->getResult()['status'], ['Stopped', 'Finished'], true));
print_r($response->getResult());
curl -X POST \
-F 'api-key=<INSERT_API_KEY>' \
-F 'batch-id=<INSERT_BATCH_ID>' \
-F 'search-engine=google' \
-F 'country=USA' \
-F 'google-location=new+york,ny' \
-F 'search-terms=["restaurant","restaurant+new+york","restaurant+manhattan"]' \
-F 'urls=["jean-georgesrestaurant.com"]' \
-F 'business-names=["Jean-Georges Restaurant"]' \
https://tools.brightlocal.com/seo-tools/api/v4/rankings/bulk-search
List<string> searches = new List<string>
{
"restaurant new york",
"restaurant manhattan",
"restaurant 10019"
};
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID {0}", batch.GetId());
Parameters parameters = new Parameters
{
["search-engine"] = "google",
["country"] = "USA",
["google-location"] = "New York, NY",
["search-terms"] = searches,
["urls"] = new List<string> { "le-bernardin.com" },
["business-names"] = new List<string>() { "Le Bernardin" }
};
try
{
// Add jobs to batch
dynamic jobResponse = batch.AddJob("/v4/rankings/bulk-search", parameters);
Console.WriteLine("Added job with IDs {0}", jobResponse["job-ids"]);
}
catch (GeneralException exception)
{
Console.WriteLine(exception.Message);
}
batch.Commit();
Console.WriteLine("Batch committed successfully, awaiting results.");
dynamic response;
do
{
Thread.Sleep(5000);
response = batch.GetResults();
} while (!(new List<string> { "Stopped", "Finished" }).Contains((string)response.status));
Console.WriteLine(response);
Success (201 Created)
{
"success": true,
"job-ids": ["1", "2","3"]
}
Failure (405 Method Not Allowed)
{
"success": false,
"errors": {
"INVALID_METHOD": "Invalid method specified. Only POST method is available"
}
}
Failure (500 Internal Server Error)
{
"success": false,
"reason": "Unable to add job(s)"
}
This method works the same as the search method above except it allows you to submit up to 100 search terms in one request. Use this when you want to look up rankings for many hundreds or thousands of search terms.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/rankings/bulk-search
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
| search-engine | Required One of google, google-mobile, google-local, bing. |
| country | Required Determines which country specific variant of the specified search engine to use. As defined in “Supported Countries”(#supported-countries) table below. |
| google-location | Allows you to optionally localize results by specifying your physical location. Specify a ZIP, city name or region. Only applicable to US searches. Also see Geo Locations method. |
| bing-location | Allows you to optionally localize results by specifying your physical location. See Geo Locations method. |
| search-terms | Required Encode as a JSON string, e.g. [“restaurant new york”, “restaurant”, “cafe”] (max 100). |
| urls | The URLs to get ranking information for. Encode as a JSON string, e.g. [“www.bluehillfarm.com”, “www.candle79.com”, “shabutatsu.com”, “marea-nyc.com”, “www.taorestaurant.com”] (max 10). |
| business-names | A list of possible business names to search for. Encode as a JSON string, e.g. [“The Rose Pub”,“Rose Pub”,“The Rose”]. For backwards compatibility this also supports a newline (\n) separated list. |
| postcode | A valid ZIP or country postal code. |
| telephone | A valid telephone number. |
| include-secondary-matches | Determines whether or not to include results matched by name, telephone and/or ZIP/postal code. One of yes or no. This should be used in conjunction with the postal and telephone parameters. |
| listings | Include details of all SERPs returned, not just the matches. Defaults to “no”. Accepts “yes” or “no”. The default is “no”. |
| screenshots | Determines whether or not to generate SERP screenshots and include the links to those screenshots in the response. Accepts “yes” or “no”. The default is “no”. |
Supported Countries
| Country | Code | Supported Engines |
|---|---|---|
| Australia | AUS | All |
| Austria | AUT | Google engines only |
| Canada (English, French) | CAN, CAN:EN, CAN:FR | All |
| Czech Republic | CZE | Google engines only |
| Denmark | DNK, DNK:DA, DNK:FO | Google engines only |
| France | FRA | Google engines only |
| Germany | DEU | Google engines only |
| Hong Kong | HKG | Google engines only |
| Ireland | IRL | All |
| Italy | ITA | Google engines only |
| Luxembourg | LUX, LUX:DE, LUX:FR | Google engines only |
| Netherlands | NLD, NLD:NL, NLD:EN | Google engines only |
| New Zealand | NZL | All |
| Norway | NOR, NOR:NO, NOR:NN | Google engines only |
| Spain | ESP, ESP:ES, ESP:CA, ESP:GL, ESP:EU | Google engines only |
| Sweden | SWE | Google engines only |
| Switzerland | CHE, CHE:DE, CHE:FR, CHE:IT, CHE:RM | Google engines only |
| Philippines | PHL | Google engines only |
| Poland | POL | Google engines only |
| Portugal | PRT | Google engines only |
| Taiwan | TWN | Google engines only |
| United Kingdom | GBR | All |
| United States | USA | All |
| United States Minor | UMI | Google engines only |
Local Directories
Fetch Profile URL (deprecated)
Batch Method
Fetch profile url for 3 local directories
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
use BrightLocal\Exceptions\BatchAddJobException;
$directories = ['google', 'yelp', 'yahoo'];
// setup API wrapper
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step 1: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
// Step 2: Add directory jobs to batch
foreach ($directories as $directory) {
try {
$response = $batch->addJob('/v4/ld/fetch-profile-url', [
'local-directory' => $directory,
'business-names' => 'La Bernardin',
'country' => 'USA',
'city' => 'New York',
'postcode' => '10019'
]);
printf('Added job with ID %d%s', $response->getResult()['job-id'], PHP_EOL);
} catch (BatchAddJobException $exception) {
printf('Error, job for directory "%s" not added. Message: %s%s', $directory, $exception->getMessage(), PHP_EOL);
}
}
// Commit batch (to indicate that all jobs have been added and that processing should start)
$batch->commit();
printf('Batch committed successfully, awaiting results.%s', PHP_EOL);
do {
sleep(5);
$response = $batch->getResults();
} while (!in_array($response->getResult()['status'], ['Stopped', 'Finished'], true));
print_r($response->getResult());
List<string> localDirectories = new List<string>
{
"google",
"yelp",
"yahoo"
};
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID {0}", batch.GetId());
foreach (string directory in localDirectories)
{
Parameters parameters = new Parameters
{
{ "business-names", "La Bernardin" },
{ "country", "USA" },
{ "city", "New York" },
{ "postcode", "10019" },
{ "local-directory", directory }
};
try
{
// Add jobs to batch
dynamic jobResponse = batch.AddJob("/v4/ld/fetch-profile-url", parameters);
Console.WriteLine("Added job with ID {0}", jobResponse["job-id"]);
}
catch (GeneralException exception)
{
Console.WriteLine(exception.Message);
}
}
batch.Commit();
Console.WriteLine("Batch committed successfully, awaiting results.");
dynamic response;
do
{
Thread.Sleep(5000);
response = batch.GetResults();
} while (!(new List<string> { "Stopped", "Finished" }).Contains((string)response.status));
Console.WriteLine(response);
Success (201 Created)
{
"success": true,
"job-id": 318
}
Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_BUSINESS_NAMES": "Invalid Business names specified",
"INVALID_COUNTRY": "Invalid country specified",
"INVALID_CITY": "Invalid city specified",
"INVALID_POSTCODE": "Invalid postcode specified",
"INVALID_LOCAL_DIRECTORY": "Invalid local directory specified"
}
}
Failure (405 Method Not Allowed)
{
"success": false,
"errors": {
"INVALID_METHOD": "Invalid method specified. Only POST method is available"
}
}
Get Batch Fetch Profile Url Results, Success (200 Ok)
{
"success": true,
"results": {
"LdFetchProfileUrl": [
{
"results": [
{
"url": null
}
],
"payload": {
"business-names": "La Bernardin\nBernardin Cafe\nBernardin restaraunt",
"country": "USA",
"city": "New York",
"postcode": "10019",
"telephone": "",
"directory": "google",
"street-address": "",
"api-key": "1a08b2e1fd07fa4150f91b80636906a9a29b8e47"
},
"status": "Completed",
"job-id": 605592911
}
]
},
"statuses": {
"Completed": 1
},
"status": "Finished"
}
Authentication for this method is via API key only.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/ld/fetch-profile-url
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
| business-names | Required A newline (\n) separated list of possible business names to search for. For example: The Rose Pub Rose Pub The Rose. |
| country | Required |
| city | Required |
| postcode | Required |
| local-directory | Required See possible options in appendix below. |
| telephone | |
| street-address |
Authentication for this method is via API key only.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/ld/fetch-profile-url
Query Parameters
| Parameter | Value | Notes |
|---|---|---|
| api-key | Required | |
| batch-id | Required | |
| local-directory | Required See possible options in appendix below. | |
| telephone | Required | |
| search-type | search-by-phone | Required |
Fetch Profile Details (by profile URL) (deprecated)
Batch Method
Fetch profile details (by profile URL)
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
use BrightLocal\Exceptions\BatchAddJobException;
$directories = [
'https://local.google.com/place?id=2145618977980482902&use=srp&hl=en',
'https://www.yelp.com/biz/le-bernardin-new-york',
];
// setup API wrapper
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step 1: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
// Step 2: Add directory jobs to batch
foreach ($directories as $directory) {
try {
$response = $batch->addJob('/v4/ld/fetch-profile-details', [
'profile-url' => $directory,
'country' => 'USA'
]);
printf('Added job with ID %d%s', $response->getResult()['job-id'], PHP_EOL);
} catch (BatchAddJobException $exception) {
printf('Error, job for directory "%s" not added. Message: %s%s', $directory, $exception->getMessage(), PHP_EOL);
}
}
// Commit batch (to indicate that all jobs have been added and that processing should start)
$batch->commit();
printf('Batch committed successfully, awaiting results.%s', PHP_EOL);
do {
sleep(5);
$response = $batch->getResults();
} while (!in_array($response->getResult()['status'], ['Stopped', 'Finished'], true));
print_r($response->getResult());
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID {0}", batch.GetId());
Parameters parameters = new Parameters
{
{ "profile-url", "https://local.google.com/place?id=2145618977980482902&use=srp&hl=en" },
{ "country", "USA" },
};
try
{
// Add jobs to batch
dynamic jobResponse = batch.AddJob("/v4/ld/fetch-profile-details", parameters);
Console.WriteLine("Added job with ID {0}", jobResponse["job-id"]);
}
catch (GeneralException exception)
{
Console.WriteLine(exception.Message);
}
batch.Commit();
Console.WriteLine("Batch committed successfully, awaiting results.");
dynamic response;
do
{
Thread.Sleep(5000);
response = batch.GetResults();
} while (!(new List<string> { "Stopped", "Finished" }).Contains((string)response.status));
Console.WriteLine(response);
Success (201 Created)
{
"success": true,
"job-id": 318
}
Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_COUNTRY": "Invalid country specified",
"INVALID_PROFILE_URL": "Profile Url is not valid"
}
}
Failure (405 Method Not Allowed)
{
"success": false,
"errors": {
"INVALID_METHOD": "Invalid method specified. Only POST method is available"
}
}
Authentication for this method is via API key only.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/ld/fetch-profile-details
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
| profile-url | Required For requests to fetch Google profile data please use our Google Link & ID Generator tool to generate your Google My Business Knowledge Panel URL. |
| country | Required |
Fetch Profile Details (by business data) (deprecated)
Batch Method
Fetch profile details (by business data)
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
use BrightLocal\Exceptions\BatchAddJobException;
$directories = ['google', 'yelp', 'yahoo'];
// setup API wrapper
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step 1: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
// Step 2: Add directory jobs to batch
foreach ($directories as $directory) {
try {
$response = $batch->addJob('/v4/ld/fetch-profile-details-by-business-data', [
'local-directory' => $directory,
'business-names' => 'La Bernardin',
'country' => 'USA',
'city' => 'New York',
'postcode' => '10019'
]);
printf('Added job with ID %d%s', $response->getResult()['job-id'], PHP_EOL);
} catch (BatchAddJobException $exception) {
printf('Error, job for directory "%s" not added. Message: %s%s', $directory, $exception->getMessage(), PHP_EOL);
}
}
// Commit batch (to indicate that all jobs have been added and that processing should start)
$batch->commit();
printf('Batch committed successfully, awaiting results.%s', PHP_EOL);
do {
sleep(5);
$response = $batch->getResults();
} while (!in_array($response->getResult()['status'], ['Stopped', 'Finished'], true));
print_r($response->getResult());
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID {0}", batch.GetId());
List<string> localDirectories = new List<string>
{
"google",
"yelp",
"yahoo"
};
foreach (string directory in localDirectories)
{
Parameters parameters = new Parameters
{
{ "business-names", "La Bernardin" },
{ "country", "USA" },
{ "city", "New York" },
{ "postcode", "10019" },
{ "local-directory", directory }
};
try
{
// Add jobs to batch
dynamic jobResponse = batch.AddJob("/v4/ld/fetch-profile-details-by-business-data", parameters);
Console.WriteLine("Added job with ID {0}", jobResponse["job-id"]);
}
catch (GeneralException exception)
{
Console.WriteLine(exception.Message);
}
}
batch.Commit();
Console.WriteLine("Batch committed successfully, awaiting results.");
dynamic response;
do
{
Thread.Sleep(5000);
response = batch.GetResults();
} while (!(new List<string> { "Stopped", "Finished" }).Contains((string)response.status));
Console.WriteLine(response);
Success (201 Created)
{
"success": true,
"job-id": 318
}
Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_BUSINESS_NAMES": "Invalid Business names specified",
"INVALID_COUNTRY": "Invalid country specified",
"INVALID_CITY": "Invalid city specified",
"INVALID_POSTCODE": "Invalid postcode specified",
"INVALID_LOCAL_DIRECTORY": "Invalid local directory specified"
}
}
Failure (405 Method Not Allowed)
{
"success": false,
"errors": {
"INVALID_METHOD": "Invalid method specified. Only POST method is available"
}
}
This method shortcuts Fetch Profile URL and Fetch Profile Details above by carrying out both in one step. It essentially looks up the URL and then uses that to fetch the profile details.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/ld/fetch-profile-details-by-business-data
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
| business-names | Required A newline (\n) separated list of possible business names to search for. For example: The Rose Pub Rose Pub The Rose. |
| country | Required |
| city | Required |
| postcode | Required |
| local-directory | Required See possible options in appendix below. |
| telephone | |
| street-address |
Reviews
Fetch Reviews (by profile URL)
Batch Method
Fetch reviews for Google+, Yahoo, and Yelp profile URLs
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
use BrightLocal\Exceptions\BatchAddJobException;
$directories = [
'https://local.google.com/place?id=2145618977980482902&use=srp&hl=en',
'https://local.yahoo.com/info-27778787-le-bernardin-new-york',
'https://www.yelp.com/biz/le-bernardin-new-york'
];
// setup API wrapper
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step 1: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
// Step 2: Add directory jobs to batch
foreach ($directories as $directory) {
try {
$response = $batch->addJob('/v4/ld/fetch-reviews', [
'profile-url' => $directory,
'country' => 'USA'
]);
printf('Added job with ID %d%s', $response->getResult()['job-id'], PHP_EOL);
} catch (BatchAddJobException $exception) {
printf('Error, job for directory "%s" not added. Message: %s%s', $directory, $exception->getMessage(), PHP_EOL);
}
}
// Commit batch (to indicate that all jobs have been added and that processing should start)
$batch->commit();
printf('Batch committed successfully, awaiting results.%s', PHP_EOL);
do {
sleep(5);
$response = $batch->getResults();
} while (!in_array($response->getResult()['status'], ['Stopped', 'Finished'], true));
print_r($response->getResult());
List<string> profileUrls = new List<string>
{
"https://local.google.com/place?id=2145618977980482902&use=srp&hl=en",
"https://local.yahoo.com/info-27778787-le-bernardin-new-york",
"https://www.yelp.com/biz/le-bernardin-new-york"
};
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID {0}", batch.GetId());
foreach (string profileUrl in profileUrls)
{
Parameters parameters = new Parameters
{
{ "country", "USA" },
{ "profile-url", profileUrl }
};
try
{
// Add jobs to batch
dynamic jobResponse = batch.AddJob("/v4/ld/fetch-reviews", parameters);
Console.WriteLine("Added job with ID {0}", jobResponse["job-id"]);
}
catch (GeneralException exception)
{
Console.WriteLine(exception.Message);
}
}
batch.Commit();
Console.WriteLine("Batch committed successfully, awaiting results.");
dynamic response;
do
{
Thread.Sleep(5000);
response = batch.GetResults();
} while (!(new List<string> { "Stopped", "Finished" }).Contains((string)response.status));
Console.WriteLine(response);
Success (201 Created)
{
"success": true,
"job-id": 318
}
Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_COUNTRY": "Invalid country specified",
"INVALID_PROFILE_URL": "Profile Url is not valid",
"INVALID_DATE_FROM": "Invalid Date From. Date Format: Y-m-d or Y-m-d H:i:s",
"INVALID_REVIEWS_LIMIT": "Reviews Limit should be positive number or 'all'"
}
}
Failure (405 Method Not Allowed)
{
"success": false,
"errors": {
"INVALID_METHOD": "Invalid method specified. Only POST method is available"
}
}
Authentication for this method is via API key only.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/ld/fetch-reviews
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
| profile-url | Required For requests to fetch Google profile data please use our Google Link & ID Generator tool to generate your Google My Business Knowledge Panel URL. |
| country | Required |
| sort | ‘rating’ or 'date’. By default 'date’. |
| reviews-limit | Positive number or 'all’. By default 100. |
| date-from | Date Format: Y-m-d or Y-m-d H:i:s. By default not specified. |
| start-page | See paging table below for details. |
Fetch Reviews (by business data)
Batch Method
Fetch reviews for a business using business data
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
use BrightLocal\Exceptions\BatchAddJobException;
$directories = ['google', 'yahoo'];
// setup API wrapper
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step 1: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
// Step 2: Add directory jobs to batch
foreach ($directories as $directory) {
try {
$response = $batch->addJob('/v4/ld/fetch-reviews-by-business-data', [
'local-directory' => $directory,
'business-names' => 'Le Bernardin',
'country' => 'USA',
'street-address' => '155 W 51st St',
'city' => 'New York',
'postcode' => '10019',
'telephone' => '(212) 554-1515'
]);
printf('Added job with ID %d%s', $response->getResult()['job-id'], PHP_EOL);
} catch (BatchAddJobException $exception) {
printf('Error, job for directory "%s" not added. Message: %s%s', $directory, $exception->getMessage(), PHP_EOL);
}
}
// Commit batch (to indicate that all jobs have been added and that processing should start)
$batch->commit();
printf('Batch committed successfully, awaiting results.%s', PHP_EOL);
do {
sleep(5);
$response = $batch->getResults();
} while (!in_array($response->getResult()['status'], ['Stopped', 'Finished'], true));
print_r($response->getResult());
List<string> localDirectories = new List<string>
{
"google",
"yahoo",
};
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID {0}", batch.GetId());
foreach (string directory in localDirectories)
{
Parameters parameters = new Parameters
{
{ "business-names", "Le Bernardin" },
{ "country", "USA" },
{ "street-address", "155 W 51st St" },
{ "city", "New York" },
{ "postcode", "10019" },
{ "telephone", "(212) 554-1515" },
{ "local-directory", directory }
};
try
{
// Add jobs to batch
dynamic jobResponse = batch.AddJob("/v4/ld/fetch-reviews-by-business-data", parameters);
Console.WriteLine("Added job with ID {0}", jobResponse["job-id"]);
}
catch (GeneralException exception)
{
Console.WriteLine(exception.Message);
}
}
batch.Commit();
Console.WriteLine("Batch committed successfully, awaiting results.");
dynamic response;
do
{
Thread.Sleep(5000);
response = batch.GetResults();
} while (!(new List<string> { "Stopped", "Finished" }).Contains((string)response.status));
Console.WriteLine(response);
Success (201 Created)
{
"success": true,
"job-id": 318
}
Success (200 Ok)
{
"success": true,
"results": {
"LdFetchProfileUrl": [
{
"results": [
{
"url": "https://www.google.com/search?q=%22%5B%22Pick+A+Bagel%22%5D%22+%2210021%22&gws_rd=cr&gl=us"
}
],
"payload": {
"business-names": "[\"Pick A Bagel\"]",
"country": "USA",
"city": "Manhattan",
"postcode": "10021",
"telephone": "(212) 717-4668",
"directory": "google",
"street-address": "1475 2nd Avenue",
"api-key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"dependent-job": {
"name": "LdFetchReviews",
"payload": {
"profile-url": null,
"country": "USA",
"date-from": null,
"reviews-limit": 250,
"sort-type": "date",
"api-key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
},
"status": "Completed",
"job-id": 549612293
},
{
"results": [
{
"url": "http://www.yelp.com/biz/pick-a-bagel-new-york-5"
}
],
"payload": {
"business-names": "[\"Pick A Bagel\"]",
"country": "USA",
"city": "Manhattan",
"postcode": "10021",
"telephone": "(212) 717-4668",
"directory": "yelp",
"street-address": "1475 2nd Avenue",
"api-key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"dependent-job": {
"name": "LdFetchReviews",
"payload": {
"profile-url": null,
"country": "USA",
"date-from": null,
"reviews-limit": 250,
"sort-type": "date",
"api-key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
},
"status": "Completed",
"job-id": 549612304
}
],
"LdFetchReviews": [
{
"results": [
{
"recommendations": [
{
"grade": "positive",
"author": "Jeremy Dayan",
"timestamp": "2016-07-30",
"text": "Nice place to have breakfast in. Relatively good prices and fast service.",
"id": "0c64b06e4c8ddaa0c6be4ba88df17f7e13cd95a0"
}
],
"reviews": [
{
"rating": 4,
"author": "Jeremy Dayan",
"timestamp": "2016-07-30",
"text": "Nice place to have breakfast in. Relatively good prices and fast service.",
"id": "0c64b06e4c8ddaa0c6be4ba88df17f7e13cd95a0"
},
{
"rating": 4,
"author": "Alain Schmid",
"timestamp": "2016-05-30",
"text": "Choose your Bagle and cream cheese from a broad range of different sets and ingredients.",
"id": "92d26048a7e297ef8911c21e35479fd2cd267d83"
},
{
"rating": 4,
"author": "David van der Loo",
"timestamp": "2016-05-30",
"text": "Okay for morning breakfast take-away.",
"id": "1d5abf2447d6d78b467fae216b630c4eef7b3eb5"
},
{
"rating": 4,
"author": "Riley Sherer",
"timestamp": "2015-09-30",
"text": "You want a bagel? Okay, pick a bagel. Come on, I don't got all day. Yeah yeah the coffee's alright.",
"id": "c88db1e509fbc2e9731f7946b84fdbfc4eb2f607"
}
],
"reviews-count":4,
"star-rating": 4
}
],
"payload": {
"profile-url": "https://www.google.com/search?q=%22%5B%22Pick+A+Bagel%22%5D%22+%2210021%22&gws_rd=cr&gl=us",
"country": "USA",
"date-from": null,
"reviews-limit": 250,
"sort-type": "date",
"api-key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"parent-id": 549612293
},
"status": "Completed",
"job-id": 549612293
},
{
"results": [
{
"reviews": [
{
"rating": 1,
"author": "Krista C.",
"timestamp": "2008-05-27",
"text": "One of the worst bagels NYC has to offer.Now I don't consider myself a bagel snob but i'm used to having a Ess-A-Bagel and a Hot Jumbo Bagel around the corner.But now after moving I needed to find my new bagel place, I thought I'd give Pick-A-Bagel a try.",
"link": "http://www.yelp.com/biz/pick-a-bagel-new-york-5?hrid=6ijWFhvccHDdiSj5MnX3yQ",
"id": "c0f1160d92b4d60bb6609b7b9d4e7be31013781e"
},
{
"rating": 1,
"author": "Jeffrey C.",
"timestamp": "2008-03-04",
"text": "I don't know about others in the store but I tried from their \"make your own pasta\" menu and had the pesto sauce for the pasta. It was the worst pesto sauce I had in my life.",
"link": "http://www.yelp.com/biz/pick-a-bagel-new-york-5?hrid=1ZIo0LYcFqmK7IJTMmw_bg",
"id": "b0223bea06d6fd8e907f41ec73cc792db538b0f9"
}
],
"reviews-count": 2,
"star-rating": "1.0"
}
],
"payload": {
"profile-url": "http://www.yelp.com/biz/pick-a-bagel-new-york-5",
"country": "USA",
"date-from": null,
"reviews-limit": 250,
"sort-type": "date",
"api-key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"parent-id": 549612304
},
"status": "Completed",
"job-id": 549612304
}
]
},
"statuses": {
"Completed": 6,
"Failed": 0
},
"status": "Finished"
}
Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_BUSINESS_NAMES": "Invalid Business names specified",
"INVALID_COUNTRY": "Invalid country specified",
"INVALID_CITY": "Invalid city specified",
"INVALID_POSTCODE": "Invalid postcode specified",
"INVALID_LOCAL_DIRECTORY": "Invalid local directory specified",
"INVALID_DATE_FROM": "Invalid Date From. Date Format: Y-m-d or Y-m-d H:i:s",
"INVALID_REVIEWS_LIMIT": "Reviews Limit should be positive number or 'all'"
}
}
Failure (405 Method Not Allowed)
{
"success": false,
"errors": {
"INVALID_METHOD": "Invalid method specified. Only POST method is available"
}
}
This method finds profile url then fetches reviews using this URL.
Authentication for this method is via API key only.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/ld/fetch-reviews-by-business-data
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
| business-names | Required A newline (\n) separated list of possible business names to search for. For example: The Rose Pub Rose Pub The Rose. |
| city | Required |
| postcode | Required |
| local-directory | Required See appendix below for possible options. |
| street-address | |
| country | Required Only USA. |
| telephone | A valid telephone number. Providing this will improve the quality of results returned. |
| sort | 'rating’ or 'date’. By default 'date’. |
| reviews-limit | Positive number or 'all’. By default 100. |
| date-from | Date Format: Y-m-d or Y-m-d H:i:s. By default not specified. |
| start-page | See paging table below for details. |
Paging
We support up to 500 reviews per request to a given directory. If you need to retrieve more than 500 reviews you can use the start-page parameter and submit multiple requests to pick up older reviews. For example with Google to fetch 1000 reviews you’d need to make two requests:
- Without start-page (or with start-page=1) to fetch reviews 1 - 500. In response, you will receive reviews and the 'next-start-page’ parameter. It can be integer page number or string token. Use it on your next request.
- With start-page='Token from previous request’ to fetch reviews next reviews.
Supported Directories
| Directory | Number Reviews Per Page or Token |
|---|---|
| token | |
| trustpilot | 20 |
| dentist1800 | 20 |
| expedia | 500 |
| token | |
| grubhub | 35 |
| healthgrades | |
| insiderpages | 50 |
| opentable | 40 |
| realself | 10 |
| selfstorage | 3 |
| tripadvisor | 5 or 10 |
| yellowpages | 20 |
Offsite SEO
Offsite SEO
Batch Method
Fetch offsite SEO information for a website address
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
use BrightLocal\Exceptions\BatchAddJobException;
$directories = [
'http://www.gramercytavern.com/',
'https://bodegawinebar.com/'
];
// setup API wrapper
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
// Step 1: Create a new batch
$batch = $api->createBatch();
printf('Created batch ID %d%s', $batch->getId(), PHP_EOL);
// Step 2: Add directory jobs to batch
foreach ($directories as $directory) {
try {
$response = $batch->addJob('/v4/seo/offsite', [
'website-url' => $directory,
]);
printf('Added job with ID %d%s', $response->getResult()['job-id'], PHP_EOL);
} catch (BatchAddJobException $exception) {
printf('Error, job for directory "%s" not added. Message: %s%s', $directory, $exception->getMessage(), PHP_EOL);
}
}
// Commit batch (to indicate that all jobs have been added and that processing should start)
$batch->commit();
printf('Batch committed successfully, awaiting results.%s', PHP_EOL);
do {
sleep(5);
$response = $batch->getResults();
} while (!in_array($response->getResult()['status'], ['Stopped', 'Finished'], true));
print_r($response->getResult());
List<string> directories = new List<string>
{
"http://www.gramercytavern.com/",
"https://bodegawinebar.com/"
};
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Batch batch = api.CreateBatch();
Console.WriteLine("Created batch ID {0}", batch.GetId());
foreach (string directory in directories)
{
Parameters parameters = new Parameters
{
{ "website-url", directory }
};
try
{
// Add jobs to batch
dynamic jobResponse = batch.AddJob("/v4/seo/offsite", parameters);
Console.WriteLine("Added job with ID {0}", jobResponse["job-id"]);
}
catch (GeneralException exception)
{
Console.WriteLine(exception.Message);
}
}
batch.Commit();
Console.WriteLine("Batch committed successfully, awaiting results.");
dynamic response;
do
{
Thread.Sleep(5000);
response = batch.GetResults();
} while (!(new List<string> { "Stopped", "Finished" }).Contains((string)response.status));
Console.WriteLine(response);
Success (201 Created)
{
"success": true,
"job-id": 318
}
Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_BATCH_ID": "Batch ID not found",
"INVALID_WEBSITE_URL": "Website URL missing"
}
}
Failure (405 Method Not Allowed)
{
"success": false,
"errors": {
"INVALID_METHOD": "Invalid method specified. Only POST method is available"
}
}
This API method returns offsite SEO information domain age, hosting location, number of pages indexed and authority. Authentication for this method is via API key only.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/seo/offsite
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| batch-id | Required |
| website-url | Required URL of the business web site. Can be specified with or without http(s). |
Clients
Add Client (deprecated)
Account Method
Creating a Client
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v1/clients-and-locations/clients', [
'name' => 'Le Bernardin',
'company-url' => 'le-bernardin.com'
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'name=Le Bernardin' \
-d 'company-url=le-bernardin.com' \
https://tools.brightlocal.com/seo-tools/api/v1/clients-and-locations/clients
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "name", "Le Bernardin" },
{ "company-url", "le-bernardin.com" }
};
Response response = api.Post("/v1/clients-and-locations/clients", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"client-id": 1
}
Adds a new client and associates it with your account.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v1/clients-and-locations/clients
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| name | Required 50 characters max. |
| company-url | Required 150 characters max |
| reference-number | An arbitrary unique reference you can use to identify a client. This may correspond to a unique value used within your system and can be useful when importing or exporting data. 50 characters max. |
Update Client (deprecated)
Account Method
Update an existing client. Only supply values you want to update. The rest will be left unchanged.
Update a Client
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$clientId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->put('/v1/clients-and-locations/clients/' . $clientId, [
'name' => 'Le Bernardin',
'company-url' => 'le-bernardin.com'
]);
print_r($response->getResult());
curl -X PUT \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'name=Le Bernardin' \
-d 'company-url=le-bernardin.com' \
https://tools.brightlocal.com/seo-tools/api/v1/clients-and-locations/clients/<client_id>
Update a client (deprecated)
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "name", "Le Bernardin" },
{ "company-url", "le-bernardin.com" }
};
Response response = api.Put("/v1/clients-and-locations/clients/" + clientId, parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"client-id": 1
}
HTTP Request
PUT https://tools.brightlocal.com/seo-tools/api/v1/clients-and-locations/clients/<client_id>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| name | 50 characters max |
| company-url | 150 characters max |
| reference-number | An arbitrary unique reference you can use to identify a client. This may correspond to a unique value used within your system and can be useful when importing or exporting data. 50 characters max. |
Delete Client (deprecated)
Account Method
Delete a Client
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$clientId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->delete('/v1/clients-and-locations/clients/' . $clientId);
var_dump($response->getResult());
if ($response->isSuccess()) {
echo 'Successfully deleted client.' . PHP_EOL;
}
int clientId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters { };
Response response = api.Delete("/v1/clients-and-locations/clients/" + clientId, parameters);
if (response.IsSuccess())
{
Console.WriteLine("Successfully deleted client");
}
else
{
Console.WriteLine(response.GetContent());
}
Success (200 OK)
{
"success": true
}
Delete an existing client. If there are reports associated with this client then the association is removed but the reports are not deleted. Warning: This action cannot be undone.
HTTP Request
DELETE https://tools.brightlocal.com/seo-tools/api/v1/clients-and-locations/clients/<client_id>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| client-id | Required |
Get Client (deprecated)
Account Method
Get a Client
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$clientId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v1/clients-and-locations/clients/' . $clientId);
print_r($response->getResult());
int clientId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Response response = api.Get("/v1/clients-and-locations/clients/" + clientId);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"client": {
"client-id":1,
"company-name": "BrightLocal",
"status": "client",
"client-reference": "BrightLocal-1"
}
}
Get extended details for a specific client.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v1/clients-and-locations/clients/<clientId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| client-id | Required |
Search Clients (deprecated)
Account Method
Search for a client
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v1/clients-and-locations/clients/search', [
'q' => 'BrightLocal'
]);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v1/clients-and-locations/clients/search?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&q=My+Sample+Query'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters {
{ "q", "BrightLocal" }
};
Response response = api.Get("/v1/clients-and-locations/clients/search", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"clients": [
{
"client-id": 1,
"company-name": "BrightLocal",
"status": "client",
"client-reference": "BrightLocal-1"
},
{
"client-id": 2,
"company-name": "BrightLocal 2",
"status": "client",
"client-reference": "BrightLocal-2"
}
]
}
Search for clients matching a specified search string.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v1/clients-and-locations/clients/search
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| q | Required |
Locations
Add Location (deprecated)
Account Method
Add Location
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/clients-and-locations/locations/', [
'name' => 'Le Bernardin',
'location-reference' => 'LE-BERNARDIN-10019',
'url' => 'le-bernardin.com',
'business-category-id' => 605,
'country' => 'USA', // 3 letter iso code
'address1' => '155 West 51st Street',
'address2' => '',
'region' => 'NY', // State or Region
'city' => 'New York',
'postcode' => '10019',
'telephone' => '+1 212-554-1515',
'opening-hours' => [
'regular' => [
'apply-to-all' => false,
'mon' => [
'status' => 'open',
'hours' => [
[
'start' => '10:00',
'end' => '18:00',
],
],
],
'tue' => [
'status' => 'split',
'hours' => [
[
'start' => '10:00',
'end' => '12:00',
],
[
'start' => '13:00',
'end' => '18:00',
]
],
],
'wed' => [
'status' => '24hrs',
'hours' => [],
],
'thu' => [
'status' => 'open',
'hours' => [
[
'start' => '10:00',
'end' => '18:00',
],
],
],
'fri' => [
'status' => 'open',
'hours' => [
[
'start' => '10:00',
'end' => '18:00',
],
],
],
'sat' => [
'status' => 'closed',
'hours' => [
[],
],
],
'sun' => [
'status' => 'closed',
'hours' => [],
],
],
'special' => [
[
'date' => '2021-01-27',
'status' => 'closed',
'hours' => [],
],
],
],
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'name=Le Bernardin' \
-d 'location-reference=LE-BERNARDIN-10019' \
-d 'url=le-bernardin.com' \
-d 'business-category-id=605' \
-d 'country=USA' \
-d 'address1=155 West 51st Street' \
-d 'address1=' \
-d 'region=NY' \
-d 'city=New York' \
-d 'postcode=10019' \
-d 'telephone=+1 212-554-1515' \
https://tools.brightlocal.com/seo-tools/api/v2/clients-and-locations/locations/
dynamic opening_hours = new
{
regular = new Dictionary<string, object>()
{
{ "apply-to-all" , false },
{ "mon" , new {
status = "open",
hours = new List<object>{
new {
start = "10:00",
end = "18:00"
}
}
}
},
{ "tue" , new {
status = "split",
hours = new List<object>{
new {
start = "10:00",
end = "12:00"
},
new {
start = "13:00",
end = "18:00"
},
}
}
},
{ "wed" , new {
status = "24hrs",
}
},
{ "thu" , new {
status = "open",
hours = new List<object>{
new {
start = "10:00",
end = "18:00"
}
}
}
},
{ "fri" , new {
status = "open",
hours = new List<object>{
new {
start = "10:00",
end = "18:00"
}
}
}
},
{ "sat" , new {
status = "closed",
}
},
{ "sun" , new {
status = "closed",
}
},
},
special = new List<object>()
{
new {
date = "2021-01-27",
status = "closed",
}
}
};
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "name", "Le Bernardin" },
{ "location-reference", "LE-BERNARDIN-1009969" },
{ "url", "le-bernardin.com" },
{ "business-category-id", "605" },
{ "country", "USA"},
{ "address1", "155 Weest 51st Street"},
{ "region", "NY"},
{ "city", "New York"},
{ "postcode", "10019"},
{ "telephone", "+1 212-554-1515"},
{ "opening-hours", opening_hours }
};
Response response = api.Post("v2/clients-and-locations/locations/", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"location-id": 1
}
Adds a new location and associates it with your account.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/clients-and-locations/locations/
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| name | Required 250 characters max. |
| client-id | |
| url | 256 characters max |
| business-category-id | Required See here for a full list of valid business codes. |
| country | Required ISO 3 country code. |
| address1 | Required 80 characters max |
| address2 | 80 characters max |
| region | Required 100 characters max |
| city | Required 100 characters max |
| postcode | Required 80 characters max |
| telephone | Required 20 characters max |
| location-reference | Required An arbitrary unique reference you can use to identify a location. This may correspond to a unique value used within your system and can be useful when importing or exporting data. 50 characters max. |
| contact-first-name | 20 characters max |
| contact-last-name | 20 characters max |
| contact-mobile | 20 characters max |
| contact-telephone | 20 characters max |
| contact-email | 100 characters max |
| contact-fax | 20 characters max |
| number-of-employees | 10 characters max |
| formation-date | Month and date formatted ‘mm-yyyy’ |
| extra-business-categories-ids | Array. For example, [1234,5678,9012]. See here for a full list of valid business category IDs. |
| opening-hours[regular][apply-to-all] | Required Boolean field |
| opening-hours[regular][mon][status] | Required Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][mon][hours][start] | Required Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][mon][hours][end] | Required Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][tue][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][tue][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][tue][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][wed][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][wed][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][wed][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][thu][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][thu][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][thu][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][fri][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][fri][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][fri][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][sat][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][sat][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][sat][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][sun][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][sun][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][sun][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[special][][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[special][][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm, Closed or N/A |
| opening-hours[special][][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm, Closed or N/A |
| opening-hours[special][][date] | Date string with format 'yyyy-mm-dd’ |
| payment-methods | Array. Available values: cash, visa, mastercard, amex, cheque, invoice, insurance, atm, travelers, financing, paypal, discover |
| short-description | 200 characters max |
| long-description | 500 characters max |
| services-of-products | Array |
Update Location (deprecated)
Account Method
Update an existing location. Only supply values you want to update. The rest will be left unchanged.
Update Location
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$locationId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->put('/v2/clients-and-locations/locations/' . $locationId, [
'name' => 'Le Bernardin',
'url' => 'le-bernardin.com',
'location-reference' => 'LE-BERNADIN-10019',
'business-category-id' => 605,
'country' => 'USA', // 3 letter iso code
'address1' => '155 West 51st Street',
'address2' => '',
'region' => 'NY', // State or Region
'city' => 'New York',
'postcode' => '10019',
'telephone' => '+1 212-554-1515',
'opening-hours' => [
'regular' => [
'apply-to-all' => true,
'mon' => [
'status' => 'open',
'hours' => [
[
'start' => '10:00',
'end' => '18:00',
]
],
],
],
],
]);
print_r($response->getResult());
curl -X PUT \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'name=Le Bernardin' \
-d 'location-reference=LE-BERNADIN-10019' \
-d 'url=le-bernardin.com' \
-d 'business-category-id=605' \
-d 'country=USA' \
-d 'address1=155 West 51st Street' \
-d 'address1=' \
-d 'region=NY' \
-d 'city=New York' \
-d 'postcode=10019' \
-d 'telephone=+1 212-554-1515' \
https://tools.brightlocal.com/seo-tools/api/v2/clients-and-locations/locations/1
int locationId =1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "name", "Le Bernardin" },
{ "location-reference", "LE-BERNARDIN-100999" },
{ "url", "le-bernardin.com" },
{ "business-category-id", "605" },
{ "country", "USA"},
{ "address1", "155 Weest 51st Street"},
{ "region", "NY"},
{ "city", "New York"},
{ "postcode", "10019"},
{ "telephone", "+1 212-554-1515"},
{ "opening-hours", new
{ special = new List<object>()
{
new {
date = "2021-12-31",
status = "closed",
}
}
}
}
};
Response response = api.Put("/v2/clients-and-locations/locations/" + locationId, parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"location-id": 1
}
HTTP Request
PUT https://tools.brightlocal.com/seo-tools/api/v2/clients-and-locations/locations/<locationId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| name | 250 characters max. |
| client-id | |
| url | 256 characters max |
| business-category-id | See here for a full list of valid business codes. |
| country | ISO 3 country code. |
| address1 | 80 characters max |
| address2 | 80 characters max |
| region | 100 characters max |
| city | 100 characters max |
| postcode | 80 characters max |
| telephone | 20 characters max |
| location-reference | Required An arbitrary unique reference you can use to identify a location. This may correspond to a unique value used within your system and can be useful when importing or exporting data. 50 characters max. |
| contact-first-name | 20 characters max |
| contact-last-name | 20 characters max |
| contact-mobile | 20 characters max |
| contact-telephone | 20 characters max |
| contact-email | 100 characters max |
| contact-fax | 20 characters max |
| number-of-employees | 10 characters max |
| formation-date | Month and date formatted 'mm-yyyy’ |
| extra-business-categories-ids | Array. For example, [1234,5678,9012]. See here for a full list of valid business category IDs. |
| opening-hours[regular][apply-to-all] | Boolean field |
| opening-hours[regular][mon][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][mon][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][mon][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][tue][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][tue][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][tue][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][wed][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][wed][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][wed][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][thu][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][thu][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][thu][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][fri][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][fri][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][fri][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][sat][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][sat][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][sat][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][sun][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[regular][sun][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[regular][sun][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm |
| opening-hours[special][][status] | Can be 'open’, 'closed’, '24hrs’, 'split’ |
| opening-hours[special][][hours][start] | Please only use allowed working hours formats such as 14:45, 2:45 pm, Closed or N/A |
| opening-hours[special][][hours][end] | Please only use allowed working hours formats such as 14:45, 2:45 pm, Closed or N/A |
| opening-hours[special][][date] | Date string with format 'yyyy-mm-dd’ |
| payment-methods | Array. Available values: cash, visa, mastercard, amex, cheque, invoice, insurance, atm, travelers, financing, paypal, discover |
| short-description | 200 characters max |
| long-description | 500 characters max |
| services-of-products | Array |
Delete Location (deprecated)
Account Method
Delete a Location
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$locationId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->delete('/v2/clients-and-locations/locations/' . $locationId);
var_dump($response->getResult());
if ($response->isSuccess()) {
echo 'Successfully deleted location.' . PHP_EOL;
}
int locationId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Response response = api.Delete("/v2/clients-and-locations/locations/" + locationId);
if (response.IsSuccess())
{
Console.WriteLine("Location successfully deleted.");
}
else
{
Console.WriteLine(response.GetContent());
}
Success (200 OK)
{
"success": true
}
Delete an existing location. If there are reports associated with this location then the association is removed but the reports are not deleted. Warning: This action cannot be undone.
HTTP Request
DELETE https://tools.brightlocal.com/seo-tools/api/v2/clients-and-locations/locations/<locationId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| location-id | Required |
Get Location (deprecated)
Account Method
Get location
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$locationId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v2/clients-and-locations/locations/' . $locationId);
print_r($response->getResult());
int locationId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Response response = api.Get("/v2/clients-and-locations/locations/" + locatonId);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"location": {
"location-name": "BrightLocal HQ",
"client-id": 1,
"location-url": "https://www.brightlocal.com",
"business-category-id": 650,
"country": "GBR",
"address1": "The Old Candlemakers",
"address2": "West St, Lewes",
"region": "East Sussex",
"town": "Lewes",
"postcode": "BN7 2NZ",
"telephone": "80500 050 0505",
"location-reference": "BL1",
"contact-first-name": "first name",
"contact-last-name": "last name",
"contact-telephone": "+44 1273 917 374",
"contact-fax": "",
"contact-mobile": "",
"num-of-employees": "50",
"formation-date": "11-2009",
"extra-business_categories": [
"marketing"
],
"extra-business-categories-ids": [
503,
2824
],
"opening-hours": {
"regular": {
"applyToAll": false,
"notSupplied": false,
"mon": {
"status": "open",
"hours": [
{
"start": "09:00",
"end": "17:30"
}
]
},
"tue": {
"status": "open",
"hours": [
{
"start": "09:00",
"end": "17:30"
}
]
},
"wed": {
"status": "open",
"hours": [
{
"start": "09:00",
"end": "17:30"
}
]
},
"thu": {
"status": "open",
"hours": [
{
"start": "09:00",
"end": "17:30"
}
]
},
"fri": {
"status": "open",
"hours": [
{
"start": "09:00",
"end": "17:30"
}
]
},
"sat": {
"status": "closed",
"hours": []
},
"sun": {
"status": "closed",
"hours": []
}
},
"special": []
},
"payment-methods-accepted": [
"visa",
"paypal"
],
"short-desc": "",
"long-desc": "",
"services-or-products": [
"analytics"
],
"external-report-url": "https://www.local-marketing-reports.com/location-dashboard/2c6c2d77e55862b302858746b2ef7a6d50ac6c4f/view"
}
}
Get extended details for a specific location.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/clients-and-locations/locations/<locationId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Search Locations (deprecated)
Account Method
Search for a location
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v2/clients-and-locations/locations/search', [
'q' => 'BrightLocal'
]);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v2/clients-and-locations/locations/search?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&q=My+Sample+Query'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters {
{ "q", "BrightLocal" }
};
Response response = api.Get("/v2/clients-and-locations/locations/search", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"locations": [
{
"location-id": 1,
"location-name":"BrightLocal HQ",
"client-id":1,
"location-reference":"BL1"
},
{
"location-id": 2,
"location-name":"Talking Elephant",
"client-id":12,
"location-reference":"TE12"
}
]
}
Search for locations matching a specified search string. The search uses a number of fields including location name, contact firstname, lastname and email address.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/clients-and-locations/locations/search
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| q | Required |
| client-id | Client Id |
Rank Checker
Add Report
Account Method
Add Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/lsrc/add', [
'location-id' => 1,
'schedule' => 'Adhoc',
'search-terms' => 'Restaurant\nfood+nyc\ndelivery+midtown+manhattan',
'website-addresses' => '["le-bernardin.com", "le-bernardin2.com"]',
'search-engines' => 'google,google-mobile,google-local,bing'
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'location-id=1' \
-d 'schedule=Adhoc' \
-d $'search-terms=Restaurant\nfood+nyc\ndelivery+midtown+manhattan' \
-d 'website-addresses=["le-bernardin.com","le-bernardin2.com"]' \
-d 'search-engines=google,google-mobile,google-local,bing' \
https://tools.brightlocal.com/seo-tools/api/v2/lsrc/add
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "location-id", 1},
{ "schedule", "Adhoc" },
{ "search-terms", "Restaurant\nfood+nyc\ndelivery+midtown+manhattan" },
{ "website-addresses", new List<string> { "le-bernardin.com", "le-bernardin.ca" } },
{ "search-engines", "google,google-mobile,google-local,bing" }
};
Response response = api.Post("/v2/lsrc/add", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"status": "Report Added",
"campaign-id": "9907",
"credits": 298
}
}
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/lsrc/add
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| name | Deprecated |
| schedule | Adhoc, Weekly or Monthly - defaults to Adhoc |
| day-of-week | Relevant to Weekly schedule only. Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday. Defaults to Tuesday. |
| day-of-month | One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, -1 (last day of month). Defaults to 1 |
| location-id | Required |
| white-label-profile-id | Deprecated (branding-profile-id is also no longer supported) |
| tags | Comma separated list of tags |
| search-terms | Required Newline (\n) separated list of search terms. |
| website-addresses | Supply one or more website addresses (max 10) as a JSON string. For example, [“test.com”,“test2.com”]. |
| website-address | (supported but deprecated) |
| website-address-2 | (supported but deprecated) |
| website-address-3 | (supported but deprecated) |
| country | One of USA, GBR, AUS, CAN:EN, CAN:FR. Defaults to USA. |
| google-location | Specify a location to perform search from. When set search keywords do not need to include a location. |
| bing-location | Specify a location to perform search from. When set search keywords do not need to include a location. |
| business-names | Newline (\n) separated list of business names |
| postcode | 80 characters max. |
| telephone | |
| search-engines | Comma separated list of search engines. Options are google, google-mobile, google-local, bing. Defaults to all search engines. |
| include-local-directory-results | Yes or No. Defaults to Yes. |
| notify | Yes or No. Defaults to No. |
| email-addresses | Newline (\n) separated list of email addresses |
| is-public | Deprecated, please use Location for update this field. |
| run-time | One of ‘00:00:00’, '03:00:00’, '06:00:00’, '09:00:00’, '12:00:00’, '15:00:00’, '18:00:00’, '21:00:00’ |
| time-zone | One of 'Pacific/Honolulu’, 'America/Los_Angeles’, 'America/Anchorage’, 'US/Pacific’, 'America/Phoenix’, 'America/Denver’, 'America/Boise’, 'US/Central’, 'Canada/Saskatchewan’, 'America/North_Dakota’, 'America/Chicago’, 'America/New_York’, 'America/Kentucky’, 'America/Indiana’, 'America/Detroit’, 'US/Eastern’, 'Canada/Atlantic’, 'Canada/Newfoundland’, 'Europe/London’, 'Europe/Dublin’, 'Australia/Perth’, 'Australia/Darwin’, 'Australia/Brisbane’, 'Australia/Sydney’, 'Pacific/Auckland’, 'US/Mountain’, 'America/North_Dakota/Center’, 'America/Kentucky/Louisville’, 'America/Indiana/Indianapolis’ |
Update Report
Account Method
Update Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/lsrc/update', [
'location-id' => 1,
'campaign-id' => 9907,
'schedule' => 'Adhoc',
'search-terms' => 'Restaurant\nfood+nyc\ndelivery+midtown+manhattan',
'website-addresses' => '["le-bernardin.com", "le-bernardin2.com"]',
'search-engines' => 'google,google-mobile,google-local,bing'
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'location-id=1' \
-d 'campaign-id=9907' \
-d 'schedule=Adhoc' \
-d $'search-terms=Restaurant\nfood+nyc\ndelivery+midtown+manhattan' \
-d 'website-addresses=["le-bernardin.com","le-bernardin2.com"]' \
-d 'search-engines=google,google-mobile,google-local,bing' \
https://tools.brightlocal.com/seo-tools/api/v2/lsrc/update
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "location-id", 1 },
{ "campaign-id", 9907 },
{ "schedule", "Adhoc" },
{ "search-terms", "Restaurant\nfood+nyc\ndelivery+midtown+manhattan" },
{ "website-addresses", new List<string> { "le-bernardin.com", "le-bernardin.ca" } },
{ "search-engines", "google,google-mobile,google-local,bing" }
};
Response response = api.Post("/v2/lsrc/update", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"status": "Report Updated",
"campaign-id": 9907
}
}
Change report settings such as name, search terms, country, website URL, schedule etc. Only specify the fields you want to change.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/lsrc/update
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| campaign-id | Required |
| name | Deprecated |
| schedule | Adhoc, Weekly or Monthly |
| day-of-week | Relevant to Weekly schedule only. Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday. |
| day-of-month | One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, -1 (last day of month). |
| location-id | Required |
| white-label-profile-id | Deprecated (branding-profile-id is also no longer supported) |
| tags | Comma separated list of tags |
| search-terms | Newline (\n) separated list of search terms |
| website-addresses | Supply one or more website addresses (max 10) as a JSON string. For example, [“test.com”,“test2.com”]. |
| website-address | (supported but deprecated) |
| website-address-2 | (supported but deprecated) |
| website-address-3 | (supported but deprecated) |
| country | One of USA, GBR, AUS, CAN:EN, CAN:FR. |
| google-location | Specify a location to perform search from. When set search keywords do not need to include a location. |
| bing-location | Specify a location to perform search from. When set search keywords do not need to include a location. |
| business-names | Newline (\n) separated list of business names |
| postcode | 80 characters max. |
| telephone | |
| search-engines | Comma separated list of search engines. Options are google, google-mobile, google-local, bing, bing-local. |
| include-local-directory-results | Yes or No |
| notify | Yes or No |
| email-addresses | Newline (\n) separated list of email addresses |
| is-public | Deprecated, please use Location for update this field. |
| run-time | One of '00:00:00’, '03:00:00’, '06:00:00’, '09:00:00’, '12:00:00’, '15:00:00’, '18:00:00’, '21:00:00’ |
| time-zone | One of ’(UTC-10:00) Hawaii’,’(UTC-08:00) Pacific Time (US & Canada)’,’(UTC-07:00) Mountain Time (US & Canada)’,’(UTC-06:00) Central Time (US & Canada)’,’(UTC-05:00) Eastern Time (US & Canada)’,’(UTC-04:00) Atlantic Time (Canada)’,’(UTC-03:30) Newfoundland’,’(UTC) Dublin, Edinburgh, London’,’(UTC+08:00) Perth’,’(UTC+09:30) Adelaide, Darwin’,’(UTC+10:00) Brisbane, Melbourne, Sydney’,’(UTC+12:00) Auckland, Wellington’ |
*if run_time and time_zone will be not provided, those will be estimated based on location
Delete Report
Account Method
Delete Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/lsrc/delete', [
'campaign-id' => 9907
]);
var_dump($response->getResult());
if ($response->isSuccess()) {
echo 'Successfully deleted report.' . PHP_EOL;
}
int campaignId = 9907;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters {
{ "campaign-id", campaignId }
};
Response response = api.Post("/v2/lsrc/delete", parameters);
if (response.IsSuccess())
{
Console.WriteLine("Successfully deleted report");
}
else
{
Console.WriteLine(response.GetContent());
}
Success (200 OK)
{
"response": {
"status": "Report Deleted"
}
}
Deletes a report and all history and ranking data associated with that report. Warning: This action cannot be undone.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/lsrc/delete
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| campaign-id | Required |
Get All Reports
Account Method
Get All Reports
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('v2/lsrc/get-all');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v2/lsrc/get-all?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters { };
Response response = api.Get("v2/lsrc/get-all", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"results": [
{
"campaign_id": "49",
"name": "Test 1",
"schedule": "Weekly",
"day_of_week": "Thursday",
"day_of_month": "0",
"location_id": "0"
},
{
"campaign_id": "50",
"name": "Test 2",
"schedule": "Weekly",
"day_of_week": "Wednesday",
"day_of_month": null,
"location_id": "0"
},
{
"campaign_id": "52",
"name": "Test 3",
"schedule": "Weekly",
"day_of_week": "Wednesday",
"day_of_month": null,
"location_id": "0"
}
]
}
}
Returns basic details about all reports associated with your account.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/lsrc/get-all
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| location-id | |
| page | Current page number. Default is 1. |
| num-per-page | Number of results per page. Default is 200. Maximum is 200. |
| no-pagination | Disable pagination. Default is 0. |
Get Report
Account Method
Get Single Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v2/lsrc/get', [
'campaign-id' => 50
]);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v2/lsrc/get?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&campaign-id=50'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters {
{ "campaign-id", 50 }
};
Response response = api.Get("/v2/lsrc/get", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"result": {
"campaign_id": "50",
"customer_id": "35",
"white_label_profile_id": "19",
"location_id": "19",
"name": "Test Pub",
"schedule": "Weekly",
"day_of_week": "Wednesday",
"day_of_month": null,
"search_terms": [
"pub fulham",
"pub in fulham",
"london pub",
"pub putney",
"beer garden in fulham",
"gastro pub fulham",
"pubs in fulham",
"fulham pubs",
"nice pub fulham",
"good pub fulham",
"nice pubs fulham",
"good pubs fulham",
"best pubs fulham",
"excellent pubs fulham",
"lovely fulham pub",
"lovely fulham pubs",
"fulham lovely pubs",
"close pub fulham",
"fulham with pubs",
"pubs around fulham",
"pubs fulham broadway",
"pub fulham broadway"
],
"ppc_search_terms": null,
"lookup_ppc": "No",
"website-addresses": [
"http://www.testpub.com/"
],
"website_address": "http://www.testpub.com/",
"website_address_2": null,
"website_address_3": null,
"country": "GBR",
"google_location": "",
"bing_location": null,
"business_names": [
"Test Pub"
],
"postcode": "TEST TEST",
"telephone": "0123456789",
"search_engines": [
"google",
"google-local",
"bing"
],
"include_local_directory_results": "Yes",
"notify": "Yes",
"email_addresses": "test@testpub.com",
"created": "2011-04-15",
"last_processed": "2013-07-18",
"last_message": "",
"currently_running": "No",
"status": "Enabled",
"red_flag": "No",
"is_public": "No",
"public_key": null,
"tags": [
"fulham",
"london",
"pub"
],
"urls": {
"public_interactive_url": "https://www.local-marketing-reports.com/location-dashboard/<HIDDEN>/ranking-reports",
"public_pdf_url": "https://www.local-marketing-reports.com/ranking-reports/<HIDDEN>/report.pdf",
"public_csv_url": "https://www.local-marketing-reports.com/ranking-reports/<HIDDEN>/report.csv"
}
}
}
}
Returns information about the specified report such as its name, search terms, country, website URL, schedule etc. You can also use this method to find out if a report is currently running (currently_running = Yes) or if the latest run failed (red_flag = Yes).
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/lsrc/get
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| campaign-id | Required |
Run Report
Account Method
Run Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/lsrc/run', [
'campaign-id' => 50
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'campaign-id=50' \
https://tools.brightlocal.com/seo-tools/api/v2/lsrc/run
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters {
{ "campaign-id", 50 }
};
Response response = api.Post("/v2/lsrc/run", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"status": "Report Run",
"campaign-id": 50,
"credits": 298
}
}
Runs the specified report if your account has sufficient monthly adhoc run credits.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/lsrc/run
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| campaign-id | Required |
Get Report History
Account Method
Get Report History
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v2/lsrc/history/get', [
'campaign-id' => 50
]);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v2/lsrc/history/get?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&campaign-id=50'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters {
{ "campaign-id", 50 }
};
Response response = api.Get("/v2/lsrc/history/get", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"results": [
{
"campaign_history_id": "25554",
"campaign_id": "50",
"location_id": "5",
"history_type": "Scheduled",
"generation_date": "2013-07-18 13:42:32"
},
{
"campaign_history_id": "25499",
"campaign_id": "50",
"location_id": "5",
"history_type": "Scheduled",
"generation_date": "2013-07-18 11:29:50"
},
{
"campaign_history_id": "25439",
"campaign_id": "50",
"location_id": "5",
"history_type": "Scheduled",
"generation_date": "2013-07-18 11:17:48"
}
]
}
}
Returns the campaign history IDs associated with all report runs for the specified report (adhoc or scheduled). These IDs can be passed to the “Get Report Results” method to return report URLs and actual ranking data.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/lsrc/history/get
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| campaign-id | Required |
Get Report Results
Account Method
Get Report Results
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v2/lsrc/results/get', [
'campaign-id' => 9636
]);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v2/lsrc/results/get?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&campaign-id=9636'
Get Report Results
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters {
{ "campaign-id", 9636 }
};
Response response = api.Get("/v2/lsrc/results/get", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"result": {
"campaign_details": {
"campaign_id": "9636",
"customer_id": "1",
"white_label_profile_id": "24",
"location_id": "0",
"name": "Alaska Bar Association",
"schedule": "Adhoc",
"day_of_week": "Monday",
"day_of_month": "18",
"search_terms": [
"Alaska Bar Association"
],
"ppc_search_terms": "",
"lookup_ppc": "No",
"website_addresses": [
"https://www.alaskabar.org/"
],
"country": "USA",
"google_location": "Alaska",
"bing_location": "",
"previous_bing_location": null,
"business_names": [
""
],
"postcode": "",
"telephone": "",
"search_engines": [
"google",
"google-local",
"bing",
],
"include_local_directory_results": "No",
"notify": "No",
"email_addresses": "test@testpub.com",
"created": "2016-01-18",
"last_processed": "2016-02-01",
"last_message": "",
"currently_running": "No",
"status": "Enabled",
"red_flag": "No",
"is_public": "Yes",
"public_key": "<hidden>",
"show_advanced_settings": "No",
"last_batch_id": "2444",
"tags": []
},
"urls": {
"interactive_url": "https://tools.brightlocal.com/seo-tools/admin/lsrc/reports/interactive/9636",
"pdf_url": "https://tools.brightlocal.com/seo-tools/admin/lsrc/reports/pdf/9636.pdf",
"csv_url": "https://tools.brightlocal.com/seo-tools/admin/lsrc/reports/csv/9636.csv",
"public_interactive_url": "http://www.local-marketing-reports.com/ranking-reports/<hidden>/9636",
"public_pdf_url": "http://www.local-marketing-reports.com/ranking-reports/<hidden>/9636.pdf",
"public_csv_url": "http://www.local-marketing-reports.com/ranking-reports/<hidden>/9636.csv"
},
"rankings": {
"keywords": [
"Alaska Bar Association"
],
"keywords_num_rankings": {
"Alaska Bar Association": "2"
},
"starred_keywords": {
"Alaska Bar Association": true
},
"extra_results": {
"Alaska Bar Association": ["local", "video"]
},
"search_engines": [
"google",
"google-places",
"bing",
],
"rankings": {
"Alaska Bar Association": {
"google": [
{
"id": "11764",
"url": "https://alaskabar.org/",
"orig_url": "https://www.alaskabar.org/",
"title": "Alaska Bar Association",
"ludocid": "",
"rank": "1",
"unblended_rank": "1",
"page": "1",
"type": "Organic",
"match": "website address",
"directory": null,
"date": "2016-02-01 19:00:24",
"hash": "32d3f35ad7633a34b2cf93dec7dfdd2455d25f84",
"search_url": "https://www.google.com/search?q=Alaska+Bar+Association&gl=us&gws_rd=cr&uule=w+CAIQICIGQWxhc2th&pws=0",
"search_engine": "google",
"sub_type": null,
"sub_rank": "1",
"last": "1"
}
],
"google-places": [
{
"id": "11766",
"url": "http://alaskabar.org/",
"orig_url": "http://www.alaskabar.org/",
"title": "Alaska Bar Association",
"ludocid": "331232242342",
"rank": "1",
"unblended_rank": "1",
"page": "1",
"type": "Places",
"match": "website address",
"directory": null,
"date": "2016-02-01 19:00:24",
"hash": "e008f8d346b2b8f124702d64be0ec1131adba959",
"search_url": "https://www.google.com/search?tbm=lcl&q=Alaska+Bar+Association&gl=us&gws_rd=cr&uule=w+CAIQICIGQWxhc2th",
"search_engine": "google-places",
"sub_type": null,
"sub_rank": "1",
"last": "1"
}
],
"bing": [
{
"id": "11770",
"url": "http://alaskabar.org/",
"orig_url": "http://www.alaskabar.org/",
"title": "Alaska Bar Association",
"ludocid": "",
"rank": "1",
"unblended_rank": "1",
"page": "0",
"type": "Organic",
"match": "website address",
"directory": null,
"date": "2016-02-01 19:00:24",
"hash": "bbd31c444764b5dd44685b5eae35578bbef68166",
"search_url": "http://www.bing.com/search?q=Alaska+Bar+Association&mkt=en-us&count=50",
"search_engine": "bing",
"sub_type": null,
"sub_rank": "0",
"last": "1"
}
],
}
},
"hashes": {
"google": {
"Alaska Bar Association": [
"32d3f35ad7633a34b2cf93dec7dfdd2455d25f84"
]
},
"google-places": {
"Alaska Bar Association": [
"e008f8d346b2b8f124702d64be0ec1131adba959"
]
},
"bing": {
"Alaska Bar Association": [
"bbd31c444764b5dd44685b5eae35578bbef68166"
]
}
},
"byPosition": {
"Position 1": {
"Alaska Bar Association||google||Organic": {
"id": "11764",
"url": "https://alaskabar.org/",
"orig_url": "https://www.alaskabar.org/",
"rank": "1",
"page": "1",
"type": "Organic",
"match": "website address",
"directory": null,
"date": "2016-02-01 19:00:24",
"hash": "32d3f35ad7633a34b2cf93dec7dfdd2455d25f84",
"search_url": "https://www.google.com/search?q=Alaska+Bar+Association&gl=us&gws_rd=cr&uule=w+CAIQICIGQWxhc2th&pws=0",
"search_engine": "google"
},
"Alaska Bar Association||google-places||Places": {
"id": "11766",
"url": "http://alaskabar.org/",
"orig_url": "http://www.alaskabar.org/",
"rank": "1",
"page": "1",
"type": "Places",
"match": "website address",
"directory": null,
"date": "2016-02-01 19:00:24",
"hash": "e008f8d346b2b8f124702d64be0ec1131adba959",
"search_url": "https://www.google.com/search?tbm=lcl&q=Alaska+Bar+Association&gl=us&gws_rd=cr&uule=w+CAIQICIGQWxhc2th",
"search_engine": "google-places"
},
"Alaska Bar Association||bing||Organic": {
"id": "11770",
"url": "http://alaskabar.org/",
"orig_url": "http://www.alaskabar.org/",
"rank": "1",
"page": "0",
"type": "Organic",
"match": "website address",
"directory": null,
"date": "2016-02-01 19:00:24",
"hash": "bbd31c444764b5dd44685b5eae35578bbef68166",
"search_url": "http://www.bing.com/search?q=Alaska+Bar+Association&mkt=en-us&count=50",
"search_engine": "bing"
}
},
"Positions 2-5": [],
"Positions 6-10": [],
"Positions 11-20": [],
"Positions 21-50": [],
"Positions 51+": {
}
},
"summary": {
"all_search_engines": {
"up": 0,
"down": 0,
"no_change": 6,
"gained_hashes": [],
"lost_hashes": []
},
"google": {
"up": 0,
"down": 0,
"no_change": 1,
"gained_hashes": [],
"lost_hashes": []
},
"google-places": {
"up": 0,
"down": 0,
"no_change": 1,
"gained_hashes": [],
"lost_hashes": []
},
"bing": {
"up": 0,
"down": 0,
"no_change": 1,
"gained_hashes": [],
"lost_hashes": []
}
}
},
"serp-screenshots": {
"google": {
"Alaska Bar Association": {
"1": {
"url": "https://brightlocal-serp-pages.s3.amazonaws.com/2016/02/01/18/a7cf190f51b2572fa166803bec9bb07920d3c678.png",
"expiry_date": "2016-03-17 19:00:24"
},
"2": {
"url": "https://brightlocal-serp-pages.s3.amazonaws.com/2016/02/01/18/e7cd9afb659ecd572c59f4556ae6f1bcf2cac665.png",
"expiry_date": "2016-03-17 19:00:24"
},
"3": {
"url": "https://brightlocal-serp-pages.s3.amazonaws.com/2016/02/01/18/593e4e97b9780de2e71e3581f1a47d784deb1c4c.png",
"expiry_date": "2016-03-17 19:00:24"
},
"4": {
"url": "https://brightlocal-serp-pages.s3.amazonaws.com/2016/02/01/18/6ddb19e8c10b899aeee8e4b11d5a8a6fa1129ebd.png",
"expiry_date": "2016-03-17 19:00:24"
},
"5": {
"url": "https://brightlocal-serp-pages.s3.amazonaws.com/2016/02/01/18/a404cc8a6c30f81a0744d6661f2004b7bcfa2a34.png",
"expiry_date": "2016-03-17 19:00:24"
}
}
}
},
"competitors": [
{
"id": 1,
"name": "Test Competitor",
"url": "https://test-competitor.com/",
"rankings": {
"bear bar": {
"google": [
{
"id": 11764,
"url": "https://alaskabar.org/",
"orig_url": "https://www.alaskabar.org/",
"title": "Test Competitor",
"ludocid": "",
"rank": 1,
"page": 1,
"type": "Organic",
"match": "website address",
"directory": null,
"hash": "32d3f35ad7633a34b2cf93dec7dfdd2455d25f84",
"search_url": "https://www.google.com/search?q=Alaska+Bar+Association&gl=us&gws_rd=cr&uule=w+CAIQICIGQWxhc2th&pws=0",
"last": 1
},
{
"id": "11764",
"url": "https://alaskabar.org/",
"orig_url": "https://www.alaskabar.org/",
"title": "Test Competitor Bar Association",
"ludocid": "",
"rank": 8,
"page": 1,
"type": "Organic",
"match": "website address",
"directory": null,
"hash": "32d3f35ad7633a34b2cf93dec7dfdd2455d25f84",
"search_url": "https://www.google.com/search?q=Alaska+Bar+Association&gl=us&gws_rd=cr&uule=w+CAIQICIGQWxhc2th&pws=0",
"last": 1
}
],
"google-places": [
{
"id": "11764",
"url": "https://alaskabar.org/",
"orig_url": "https://www.alaskabar.org/",
"title": "Alaska Bar Association",
"ludocid": "546467123423233",
"rank": 1,
"page": 1,
"type": "Organic",
"match": "website address",
"directory": null,
"hash": "32d3f35ad7633a34b2cf93dec7dfdd2455d25f84",
"search_url": "https://www.google.com/search?q=Alaska+Bar+Association&gl=us&gws_rd=cr&uule=w+CAIQICIGQWxhc2th&pws=0",
"last": 1
}
]
}
}
}
]
}
}
}
If no campaign history ID or previous campaign history ID are passed then the latest results for the specified report are returned.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/lsrc/results/get
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| campaign-id | Required |
| campaign-history-id | If both campaign-history-id and previous-campaign-history-id are not specified then the latest report is returned. |
| previous-campaign-history-id | If both campaign-history-id and previous-campaign-history-id are not specified then the latest report is returned. |
Citation Tracker
Add Report
Account Method
Add Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/ct/add', [
'location-id' => 1,
'business-type' => 'Restaurant',
'primary-location' => '10020'
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'location-id=1' \
-d 'business-type=Restaurant' \
-d 'primary-location=10020' \
https://tools.brightlocal.com/seo-tools/api/v2/ct/add
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "location-id", 1 },
{ "business-type", "Restaurant" },
{ "primary-location", "10019" },
};
dynamic response = api.Post("v2/ct/add", parameters).GetContent();
Console.WriteLine(response);
Success (200 OK)
{
"response": {
"status": "added",
"report-id": 682
}
}
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/ct/add
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| location-id | Required You can specify location ID or unique reference to create report for a location |
| report-name | Deprecated, please use Location for updating this field. |
| business-name | Deprecated, please use Location for updating this field. |
| address-1 | Deprecated, please use Location for updating this field. |
| address-2 | Deprecated, please use Location for updating this field. |
| business-location | Deprecated, please use Location for updating this field. |
| postcode | Deprecated, please use Location for updating this field. |
| country | Deprecated, please use Location for updating this field. |
| phone | Deprecated, please use Location for updating this field. |
| website | Deprecated, please use Location for updating this field. |
| business-type | Required Business type (e.g. Hotel) NOT a business category (e.g. Hotels & Guest houses). |
| state-code | Deprecated, please use Location for updating this field. |
| monthly-run | One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31. Defaults to 0 (none). |
| weekly-run | One of 1, 2, 3, 4, 5, 6, 7. Defaults to 0 (none). |
| white-label-profile-id | Deprecated, please use Location for updating this field. |
| active-only | Deprecated |
| notify | One of yes or no. If set to yes we will send report alerts to all email addresses specified (see field below). If you include customer email addresses when setting up your report we’ll also email them the alerts so please be sure this is what you want before adding their addresses. Default is no. |
| email-addresses | Supply one or more (max 5) email addresses for us to send report alerts to. Emails should be passed as a JSON encoded array. This only takes effect if notify is set to yes. |
| is-public | Deprecated, please use Location for update this field. |
| primary-location | Required We use ‘Location’ to identify your top 10 ‘Google+ Local’ competitors. Please enter your city/town name or zip/postcode. Note: for US businesses we strongly recommend that you use only 5 digit zips (99750, NOT 99750-0077) as using the longer format can make it harder for us to find competitors. |
Update Report
Account Method
Update Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/ct/update', [
'location-id' => 1,
'report-id' => 682,
'business-type' => 'Restaurant',
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'location-id'=1,
-d 'report-id'=682,
-d 'business-type=Restaurant' \
https://tools.brightlocal.com/seo-tools/api/v2/ct/update
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "location-id", 1 },
{ "report-id", 682 },
{ "business-type", "Restaurant" },
{ "primary-location", "10019" },
};
dynamic response = api.Post("v2/ct/update", parameters).GetContent();
Console.WriteLine(response);
Success (200 OK)
{
"response": {
"status": "edited"
}
}
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/ct/update
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| location-id | Required You can specify location ID or unique reference to create report for a location. |
| report-id | Required |
| report-name | Deprecated, please use Location for updating this field. |
| business-name | Deprecated, please use Location for updating this field. |
| address-1 | Deprecated, please use Location for updating this field. |
| address-2 | Deprecated, please use Location for updating this field. |
| business-location | Deprecated, please use Location for updating this field. |
| postcode | Deprecated, please use Location for updating this field. |
| country | Deprecated, please use Location for updating this field. |
| phone | Deprecated, please use Location for updating this field. |
| website | Deprecated, please use Location for updating this field. |
| business-type | Business type (e.g. Hotel) NOT a business category (e.g. Hotels & Guest houses). |
| location | |
| state-code | Deprecated, please use Location for updating this field. |
| monthly-run | One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31. Defaults to 0 (none). |
| weekly-run | One of 1, 2, 3, 4, 5, 6, 7. Defaults to 0 (none). |
| white-label-profile-id | Deprecated, please use Location for updating this field. |
| active-only | Deprecated |
| notify | One of yes or no. If set to yes we will send report alerts to all email addresses specified (see field below). If you include customer email addresses when setting up your report we’ll also email them the alerts so please be sure this is what you want before adding their addresses. Default is no. |
| email-addresses | Supply one or more (max 5) email addresses for us to send report alerts to. Emails should be passed as a JSON encoded array. This only takes effect if notify is set to yes. |
| is-public | Deprecated, please use Location for update this field. |
Get Report
Account Method
Get Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v2/ct/get', [
'report-id' => 682
]);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v2/ct/get?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&report-id=682'
int reportId = 682;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Response report = api.Get("v2/ct/get", new Parameters { { "report-id", reportId } });
Console.WriteLine(report.GetContent());
Success (200 OK)
{
"success": true,
"report": {
"report_id": "255565",
"customer_id": "88",
"location_id": "1",
"weekly_run": "3",
"monthly_run": "0",
"report_name": "The View",
"website_address": "www.ullubatanc.com",
"business_name": "Ullu Bata Inc.",
"business_location": "London",
"postcode": "ABCD1234",
"country": "GBR",
"state_code": null,
"address1": "",
"address2": "",
"telephone": "01273 207 100",
"business_type": "Restaurant",
"primary_location": "Brighton",
"last_run_id": "1185703",
"last_run": "2015-10-28 05:31:59",
"company_name": "Ullu Bata Inc.",
"white_label_profile_id": "7819",
"notify": "0",
"email_addresses": "[\"example@brightlocal.com\"]",
"active_only": "",
"is_public": "Yes",
"public_key": "<REPLACED>",
"created": "2015-10-28 05:00:34",
"status": "complete",
"urls": {
"interactive_url": "https:\/\/tools.brightlocal.com\/seo-tools\/admin\/ct\/reports\/view\/255565",
"pdf_url": "https:\/\/tools.brightlocal.com\/seo-tools\/admin\/ct\/reports\/pdf\/255565",
"csv_url": "https:\/\/tools.brightlocal.com\/seo-tools\/admin\/ct\/reports\/csv\/255565",
"public_interactive_url": "<REPLACED>",
"public_pdf_url": "<REPLACED>",
"public_csv_url": "<REPLACED>"
}
}
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/ct/get
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| report-id | Required |
Run Report
Account Method
Run Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/ct/run', [
'report-id' => 682
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'report-id=682' \
https://tools.brightlocal.com/seo-tools/api/v2/ct/run
int reportId = 682;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "report-id", reportId }
};
Response response = api.Post("v2/ct/run", parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"status": "running"
}
}
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/ct/run
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| report-id | Required |
Delete Report
Account Method
Delete Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v2/ct/delete', [
'report-id' => 682
]);
var_dump($response->getResult());
if ($response->isSuccess()) {
echo 'Successfully deleted report.' . PHP_EOL;
}
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'report-id=682' \
https://tools.brightlocal.com/seo-tools/api/v2/ct/delete
int reportId = 682;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Response status = api.Post(
"v2/ct/delete",
new Parameters { { "report-id", reportId } });
Console.WriteLine(status.GetContent());
Success (200 OK)
{
"response": {
"status": "deleted"
}
}
Warning: This action cannot be undone.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v2/ct/delete
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| report-id | Required |
Get All Reports
Account Method
Get All Reports
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v2/ct/get-all');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v2/ct/get-all?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int locationId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Response reports = api.Get("v2/ct/get-all");
Console.WriteLine(reports.GetContent());
Success (200 OK)
{
"response": {
"results": [
{
"report_id": "278",
"customer_id": "35",
"location_id": "5",
"report_run_id": "2457",
"report_name": "Test 1",
"website_address": "http://www.test1.com",
"business_name": "Test 1",
"business_location": "Test location",
"postcode": "TEST TEST",
"country": "GBR",
"state_code": null,
"cancel_run": "0",
"address1": "",
"address2": "",
"telephone": "0123456789",
"business_type": "Pub",
"primary_location": "Fulham",
"currently_running": "No",
"generation_error": "No",
"terminal_fail": "No",
"last_run": "2012-09-07 11:45:56",
"report_status": null,
"your_ct_count": "197",
"your_ct_count_up": "0",
"your_ct_count_down": "0",
"total_ct_sources": "230",
"total_ct_sources_up": "0",
"competitor_ct_count": "76",
"competitor_ct_count_diff": null,
"old_ct_count": "0",
"company_name": null,
"branding_profile_id": null,
"notify": "0",
"email_addresses": "['test@test1.com']",
"your_ct_count_diff": 0,
"competitor_ct_count_up": 0,
"competitor_ct_count_down": 0,
"total_ct_sources_diff": 0,
"successful_runs": "1"
},
{
"report_id": "660",
"customer_id": "35",
"location_id": "0",
"report_run_id": "2756",
"report_name": "Test 2",
"website_address": "",
"business_name": "Test 2",
"postcode": "chicago",
"country": "USA",
"state_code": "IL",
"cancel_run": "0",
"address1": "",
"address2": "",
"telephone": "0123456789",
"business_type": "car hire",
"primary_location": "chicago",
"currently_running": "No",
"generation_error": "No",
"terminal_fail": "No",
"last_run": "2013-05-21 11:18:31",
"report_status": null,
"your_ct_count": "633",
"your_ct_count_up": "129",
"your_ct_count_down": "0",
"total_ct_sources": "356",
"total_ct_sources_up": "100",
"competitor_ct_count": "90",
"competitor_ct_count_diff": "10",
"old_ct_count": "0",
"company_name": null,
"branding_profile_id": null,
"notify": "0",
"email_addresses": "['test@test2.com']",
"your_ct_count_diff": 0,
"competitor_ct_count_up": 0,
"competitor_ct_count_down": 0,
"total_ct_sources_diff": 0,
"successful_runs": "2"
}
]
}
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/ct/get-all
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| location-id |
Get Report Results
Account Method
Get Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v2/ct/get-results', [
'report-id' => 2457
]);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v2/ct/get-results?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&report-id=2457'
int reportId = 2457;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Response response = api.Get("v2/ct/get-results", new Parameters
{
{ "report-id", reportId }
});
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"results": {
"active": [
{
"id": "",
"citation_id": 182555,
"customer_id": "35",
"report_id": "2457",
"citation-status": "active",
"source": "carricktoday.co.uk",
"url": "http://www.carricktoday.co.uk/findit?action=showMap&placeid=68739",
"citation-notes": null,
"status": "Got it",
"date-identified-sorting": "2012-09-07T00:00:00+00:00",
"date-identified": "07 Sep 12",
"domain-authority": "38.75",
"citation-value": "Unknown",
"moz-rank": "Unknown",
"site-type": "Local Directory",
"listing-type": "Free Listing",
"seomoz-lookup-complete": "Yes",
"business-name": null,
"postcode": null
}
],
"pending": [
],
"possible": [
],
"activeDomains": {
"facebook.com": true,
"twitter.com": true,
"yelp.com": true,
"yell.com": true,
"thomsonlocal.com": true,
"beerintheevening.com": true,
"hotfrog.co.uk": true,
"cylex-uk.co.uk": true
},
"pendingDomains": {
},
"possibleDomains": {
},
"topDirectories": [
{
"citation_id": 182555,
"customer_id": "35",
"report_id": "2457",
"citation-status": "active",
"source": "carricktoday.co.uk",
"url": "http://www.carricktoday.co.uk/findit?action=showMap&placeid=68739",
"citation-notes": null,
"status": "Got it",
"date-identified-sorting": "2012-09-07T00:00:00+00:00",
"date-identified": "07 Sep 12",
"domain-authority": "38.75",
"citation-value": "Unknown",
"moz-rank": "Unknown",
"site-type": "Local Directory",
"listing-type": "Free Listing",
"seomoz-lookup-complete": "Yes",
"business-name": "John's business",
"address": "Lungomare Zara, 1234 Giulianova",
"postcode": "1234",
"website-url": "http://www.johns-s-business.co.uk/",
"telephone": "03 12345678"
}
],
"flags": {
"customer": {
"new": [],
"disappeared": []
},
"competitor": {
"new": [],
"disappeared": []
}
},
"competitors": {
}
}
}
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v2/ct/get-results
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| report-id | Required |
Geo Locations
Bing
Account Method
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v1/geo-locations/bing', [
'country' => 'USA',
'location' => '12555'
]);
var_dump($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v1/geo-locations/bing?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&country=USA&location=12555'
Api api = new Api("<YOUR_API_KEY>", "<YOUR_API_SECRET>");
var results = api.get("v1/geo-locations/bing");
Success (200 OK)
Validation Failure (400 Bad Request)
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v1/geo-locations/bing
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| country | Required One of USA, GBR, CAN or AUS. |
| location | Required Like “new york”. |
Account Method
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v1/geo-locations/google', [
'location' => "12555"
]);
var_dump($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v1/geo-locations/google?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&location=12555'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
var results = api.get("v1/geo-locations/google");
Success (200 OK)
Validation Failure (400 Bad Request)
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v1/geo-locations/google
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| country | Required One of USA, GBR, CAN or AUS. |
| location | Required Like “new york”. |
Citation Builder
Reputation Manager
Add Report
Account Method
Add Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v4/rf/add', [
'location-id' => 1,
'directories' => [
'yellowbot' => [
'url' => 'https://www.yellowbot.com/le-bernardin-new-york-ny.html',
'include' => true,
],
'yellowpages' => [
'url' => 'https://www.yellowpages.com/new-york-ny/mip/le-bernardin-9909153',
'include' => true,
],
'yelp' => [
'url' => 'https://www.yelp.com/biz/le-bernardin-new-york',
'include' => true,
],
],
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'location-id=1' \
https://tools.brightlocal.com/seo-tools/api/v4/rf/add
Dictionary<string, object> directories = new Dictionary<string, object>()
{
{
"yellowbot", new {
url = "https://www.yellowbot.com/le-bernardin-new-york-ny.html",
include = true
}
}
};
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "location-id", 1 },
{ "directories", directories }
};
dynamic response = api.Post("v4/rf/add", parameters).GetContent();
Console.WriteLine(response);
Example of specifying directories
<?php
echo json_encode([
'yellowbot' => [
'url' => 'https://www.yellowbot.com/le-bernardin-new-york-ny.html',
'include' => true,
],
'yellowpages' => [
'url' => 'https://www.yellowpages.com/new-york-ny/mip/le-bernardin-9909153',
'include' => true,
],
'yelp' => [
'url' => 'https://www.yelp.com/biz/le-bernardin-new-york',
'include' => true,
],
]);
var directories = new List<dynamic>();
directories.Add(new
{
yellowbot = new
{
url = "http://www.yellowbot.com/le-bernardin-new-york-ny.html",
include = true
},
yellowpages = new
{
url = "http://www.yellowpages.com/new-york-ny/mip/le-bernardin-9909153",
include = true
},
yelp = new
{
url = "",
include = true
}
});
Success (201 Created)
{
"success": true,
"report-id": "1"
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_LOCATION": "Location ID is required"
}
}
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/rf/add
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| report-name | Deprecated, please use Location for update this field. |
| location-id | Required Associate this report with a location in your account. This ID needs to correspond to a valid location in your account. |
| white-label-profile-id | Deprecated, please use Location for update this field. |
| business-name | Deprecated, please use Location for update this field. |
| contact-telephone | Deprecated, please use Location for update this field. |
| address1 | Deprecated, please use Location for update this field. |
| address2 | Deprecated, please use Location for update this field. |
| city | Deprecated, please use Location for update this field. |
| postcode | Deprecated, please use Location for update this field. |
| country | Deprecated, please use Location for update this field. |
| schedule | D (Daily), W (Weekly) or M (Monthly). You to purchase an add on before you can use daily reporting. Defaults to M (Monthly). |
| run-on | Numeric day of week or day of month to run the report on (applicable to weekly and monthly schedules). Defaults to current day of month. If you create your report today it’ll be run on the 17th of each month unless you specify otherwise. |
| receive-email-alerts | One of 0, 1 or 2. If set to 1 we will send report alerts every time a report finishes (regardless of whether or not new reviews were found) to all email addresses specified (see field below). If you include customer email addresses when setting up your report we’ll also email them the alerts so please be sure this is what you want before adding their addresses. If set to 2 we will only send email alerts if new reviews were found upon report completion. Defaults to 0 which means no alerts will be sent. |
| alert-email-addresses | Supply a list of email addresses as a JSON string, e.g. [“user1@test.com”,“user2@test.com”,“user3@test.com”] |
| is-public | Deprecated, please use Location for update this field. |
| directories | By default we try and find profile URLs and reviews in all directories we support. If you’d like your report to contain only specific directories or already know the profile URLs for some directories you can supply them here. Please note that if you supply information for this parameter you need to give us all details of the directories you want included. If you have profile URLs for some but not others you can leave those URL fields empty and we’ll do our best to find them. Generally we recommend you run your report for the first time without this setting and then use our update method to add/change URLs or remove directories if needed. The data for this parameter needs to be supplied as a JSON string. Local directory identifiers (the keys in the example below) are documented here. Here’s an example of how to generate suitable values in PHP: |
Update Report
Account Method
Update Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->put('/v4/rf/' . $reportId, [
'location-id' => 1,
]);
print_r($response->getResult());
curl -X PUT \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'location-id=1' \
-d 'schedule=Adhoc' \
-d 'day_of_month=2' \
https://tools.brightlocal.com/seo-tools/api/v4/rf/1
int reportId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic directories = new
{
yellowbot = new
{
url = "https://www.yellowbot.com/le-bernardin-new-york-ny.html",
include = true
},
yelp = new
{
url = "",
include = false
}
};
Parameters parameters = new Parameters
{
{ "location-id", 1 },
{ "directories", directories }
};
dynamic reviews = api.Put("v4/rf/" + reportId, parameters).GetContent();
Console.WriteLine(reviews);
Example of modifying directories
<?php
echo json_encode([
'yellowbot' => [
'url' => 'https://www.yellowbot.com/le-bernardin-new-york-ny.html',
'include' => true,
],
'yellowpages' => [
'url' => 'https://www.yellowpages.com/new-york-ny/mip/le-bernardin-9909153',
'include' => true,
],
'yelp' => [
'url' => 'https://www.yelp.com/biz/le-bernardin-new-york',
'include' => true,
],
]);
var directories = new List<dynamic>();
directories.Add(new
{
yellowbot = new
{
url = "http://www.yellowbot.com/le-bernardin-new-york-ny.html",
include = true
},
yellowpages = new
{
url = "http://www.yellowpages.com/new-york-ny/mip/le-bernardin-9909153",
include = true
},
yelp = new
{
url = "",
include = true
}
});
> Success (200 Created)
```json
{
"success": true
}
HTTP Request
PUT https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| location-id | Required |
| report-name | Deprecated, please use Location for update this field. |
| white-label-profile-id | Deprecated, please use Location for update this field. |
| schedule | D (Daily), W (Weekly) or M (Monthly). You to purchase an add on before you can use daily reporting. Defaults to M (Monthly). |
| run-on | Numeric day of week or day of month to run the report on (applicable to weekly and monthly schedules). Defaults to current day of month. If you create your report today it’ll be run on the 17th of each month unless you specify otherwise. |
| receive-email-alerts | One of 0, 1 or 2. If set to 1 we will send report alerts every time a report finishes (regardless of whether or not new reviews were found) to all email addresses specified (see field below). If you include customer email addresses when setting up your report we’ll also email them the alerts so please be sure this is what you want before adding their addresses. If set to 2 we will only send email alerts if new reviews were found upon report completion. Defaults to 0 which means no alerts will be sent. |
| alert-email-addresses | Supply a list of email addresses as a JSON string, e.g. [“user1@test.com”,“user2@test.com”,“user3@test.com”] |
| is-public | Deprecated, please use Location for update this field. |
| directories | If you need to add or change a profile URL you can do so here. The data for this parameter needs to be supplied as a JSON string. Local directory identifiers (the keys in the example below) are documented here. Here’s an example of how to generate suitable values in PHP: |
Get Report
Account Method
Get Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/' . $reportId);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf/1?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic report = api.Get("v4/rf/" + reportId).GetContent();
Console.WriteLine(report);
Success (200 OK)
{
"success": true,
"report": {
"report_id": "270",
"report_name": "Le Bernardin",
"location_id": "0",
"customer_id": "35",
"business_name": "Le Bernardin",
"contact_telephone": "+1 212-554-1515",
"address1": "155 West 51st Street",
"address2": "",
"city": "New York",
"postcode": "10019",
"country": "USA",
"receive_email_alerts": false,
"alert_email_addresses": [
"<hidden>",
"<hidden>",
"<hidden>"
],
"last_update": "2015-01-06 11:51:35",
"created_at": "2015-01-06 11:43:57",
"schedule": "M",
"run_on": "1",
"reviews_count": "2772",
"rating": "4.49",
"is_running": false,
"white_label_profile_id": null,
"is_public": true,
"public_key": "<hidden>",
"directories": {
"botw": {
"url": "http://local.botw.org/New_York/New_York/Ayza/1000053931.html",
"searched": true,
"include": true
},
"citysearch": {
"url": "http://www.citysearch.com/profile/7143737/new_york_ny/le_bernardin.html",
"searched": true,
"include": true
},
"dexknows": {
"url": "",
"searched": true,
"include": true
},
"foursquare": {
"url": "https://foursquare.com/v/le-bernardin-new-york-ny/3fd66200f964a52066e31ee3",
"searched": true,
"include": true
},
"google": {
"url": "https://plus.google.com/106100547192468577963/about?hl=en&rfmt=s",
"searched": true,
"include": true
},
"insiderpages": {
"url": "http://www.insiderpages.com/b/15241026606/le-bernardin-new-york-1",
"searched": true,
"include": true
},
"judysbook": {
"url": "http://www.judysbook.com/Le-Bernardin-Restaurant-Home-and-Garden-newyork-r29294246.htm",
"searched": true,
"include": true
},
"kudzu": {
"url": "http://www.kudzu.com/m/Le-Bernardin-20063962",
"searched": true,
"include": true
},
"localcom": {
"url": "http://www.local.com/business/details/new-york-ny/le-bernardin-117822808/",
"searched": true,
"include": true
},
"manta": {
"url": "http://www.manta.com/c/mmgg127/le-bernardin-restaurant",
"searched": true,
"include": true
},
"merchantcircle": {
"url": "http://www.merchantcircle.com/business/le.Bernardin.212-554-1515",
"searched": true,
"include": true
},
"superpages": {
"url": "http://www.superpages.com/bp/New-York-NY/Le-Bernardin-L0500767889.htm",
"searched": true,
"include": true
},
"yahoo": {
"url": "https://local.yahoo.com/info-27778787-le-bernardin-new-york",
"searched": true,
"include": true
},
"yellowbot": {
"url": "http://www.yellowbot.com/le-bernardin-new-york-ny.html",
"searched": true,
"include": true
},
"yellowpages": {
"url": "http://www.yellowpages.com/new-york-ny/mip/le-bernardin-9909153",
"searched": true,
"include": true
},
"yelp": {
"url": "http://www.yelp.com/biz/le-bernardin-new-york",
"searched": true,
"include": true
}
},
"urls": {
"interactive_url": "https://tools.brightlocal.com/seo-tools/admin/rf/tracker/276",
"pdf_url": "https://tools.brightlocal.com/seo-tools/admin/rf/pdf-report/276",
"public_interactive_url": "http://www.local-marketing-reports.com/review-reports/<hidden>/tracker/276",
"public_pdf_url": "http://www.local-marketing-reports.com/review-reports/<hidden>/276.pdf"
}
}
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID missing"
}
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Delete Report
Account Method
Delete Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->delete('/v4/rf/' . $reportId);
var_dump($response->getResult());
if ($response->isSuccess()) {
echo 'Successfully deleted report.' . PHP_EOL;
}
curl -X DELETE \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
https://tools.brightlocal.com/seo-tools/api/v4/rf/1
int reportId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic status = api.Delete("v4/rf/" + reportId).GetContent();
Console.WriteLine(status);
Success (200 OK)
{
"success": true
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID": "Report ID missing"
}
}
Failure when report running (400 Bad Request)
{
"success": false,
"errors": {
"REPORT_RUNNING": "Report is running"
}
}
HTTP Request
DELETE https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Get Reports
Account Method
Get Reports
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic report = api.Get("v4/rf").GetContent();
Console.WriteLine(report);
Success (200 OK)
{
"success": true,
"reports": [
{
"report_id": "270",
"report_name": "Le Bernardin",
"location_id": "0",
"created_at": "2015-01-06 11:43:57",
"last_update": "2015-01-06 11:51:35",
"is_running": false,
"running_message": "",
"fetching": false,
"complete": true
},
{
"report_id": "141",
"report_name": "Zuni cafe #2",
"location_id": "0",
"created_at": "2013-12-10 15:24:53",
"last_update": "2014-12-15 02:07:38",
"is_running": false,
"running_message": "",
"fetching": false,
"complete": true
},
{
"report_id": "119",
"report_name": "Zuni Cafe",
"location_id": "0",
"created_at": "2013-10-21 10:23:00",
"last_update": "2014-12-15 02:06:54",
"is_running": false,
"running_message": "",
"fetching": false,
"complete": true
},
{
"report_id": "144",
"report_name": "Slade & Baker Vision Center",
"location_id": "0",
"created_at": "2013-12-16 15:17:10",
"last_update": "2014-12-15 02:05:48",
"is_running": false,
"running_message": "",
"fetching": false,
"complete": true
}
]
}
Validation Failure (400 Bad Request)
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| location-id | Filter the list of reports returned by location ID. This ID must correspond to a valid location in your account. |
Report Search
Account Method
Search for a Reputation Manager Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/search', [
'q' => 'Le Bernardin'
]);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf/search?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>&q=My+Sample+Query'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "q", "Le Bernardin" }
};
dynamic report = api.Get("v4/rf/search", parameters).GetContent();
Console.WriteLine(report);
Success (200 OK)
{
"success": true,
"reports": [
{
"report_id": "270",
"report_name": "Le Bernardin",
"location_id": "0",
"created_at": "2015-01-06 11:43:57",
"last_update": "2015-01-06 11:51:35",
"is_running": false,
"running_message": "",
"fetching": false,
"complete": true
}
]
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_SEARCH": "Search string missing"
}
}
Search for reports in your account.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf/search
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| q | Required Supply an arbitrary search string. |
Get Reviews
Account Method
Get Reviews
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 141;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/' . $reportId . '/reviews');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf/141/reviews?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId = 141;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Parameters parameters = new Parameters
{
{ "limit", 100 }
};
dynamic reviews = api.Get("v4/rf/" + reportId + "/reviews", parameters).GetContent();
Console.WriteLine(reviews);
Success (200 OK)
{
"success": true,
"reviews": [
{
"dt": "2014-12-15 02:04:16",
"report_id": "141",
"directory": "yelp",
"timestamp": "2014-12-14 02:04:43",
"rating": "1",
"title": "",
"author": "Stephen Z.",
"text": "I have not been in a number of years. Went there this past Friday night and was beyond disappointed. Service was not great at the bar or during dinner. The squash appetizer was completely overwhelmed by a very strong garlic component. The size of the main courses were about the size of the appetizers. I had the pork which looked like dog food with a side of beans. The meat was over cooked and was over powered by one spice. The fish was the same and the pasta dish looked like it had four or five pieces. The desserts were not much better. It was a very sad, disappointing experience. Will not be back.",
"link": "http://www.yelp.com/biz/zuni-cafe-san-francisco?hrid=O-VJJEgwqsi02q4YnOJ8Qw",
"url": "http://www.yelp.com/biz/zuni-cafe-san-francisco",
"source": "",
"name": "Yelp",
"report_run_id": "15608"
},
{
"dt": "2014-12-15 02:04:16",
"report_id": "141",
"directory": "yelp",
"timestamp": "2014-12-11 02:04:43",
"rating": "4",
"title": "",
"author": "Carl A.",
"text": "After years of 5 stars from me, we had our first so-so experience at Zuni. Is it slipping now? I hope not. But the buzz was gone. The service was halting and off. Let's hope that it was just an off-night, but maybe the time has come to move on??",
"link": "http://www.yelp.com/biz/zuni-cafe-san-francisco?hrid=0xdzL2swNvC6cQ8yUDL4XQ",
"url": "http://www.yelp.com/biz/zuni-cafe-san-francisco",
"source": "",
"name": "Yelp",
"report_run_id": "15608"
},
{
"dt": "2014-12-15 02:04:16",
"report_id": "141",
"directory": "yelp",
"timestamp": "2014-12-10 02:04:43",
"rating": "3",
"title": "",
"author": "Mary B.",
"text": "Very expensive over rated restaurant. I feel the city has lost its zest for good food and overcharges for the mediocre. Maybe we all should start eating at the food trucks where people cook their hearts out and keep the prices affordable. Pork chop (from Llano Secco) delicious. Nettles? Isn't spinach just as good. My husband thought the Ceasar salad was one of the best he's ever had, but the spaghetti was inedible. Thought he should have stopped at the Caesar's. I'm not going back. I can find better food at better prices in this city.",
"link": "http://www.yelp.com/biz/zuni-cafe-san-francisco?hrid=SEB7nqhlzF8pg2PALEvI7Q",
"url": "http://www.yelp.com/biz/zuni-cafe-san-francisco",
"source": "",
"name": "Yelp",
"report_run_id": "15608"
}
]
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID missing"
}
}
Fetch all reviews associated with a report.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>/reviews
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| directory | Fetch reviews for a specific directory. See directory identifiers in appendix below. |
| stars | Fetch reviews for a specific star rating (0-5). |
| sort | By date “asc” or “desc”. Default is “asc” |
| from | Fetch reviews from specified date. Format yyyy-mm-dd. |
| to | Fetch reviews up until specified date. Format yyyy-mm-dd. |
| offset | By default 20 reviews are returned at once. Use in combination with limit to page results. Defaults to 0. |
| limit | Defaults to 20. |
Response Fields Explained
A few of the fields are explained below:
| Field | Explanation |
|---|---|
| source | Determines where a review came from. Yahoo!, for example, can contain reviews that were posted directly on Yahoo! and reviews that have been sourced from Yelp. |
| source_link | Link to the site where the review was originally written. |
| hash | Unique identifier based on directory, author and review text. This can be used when storing reviews locally to prevent duplicates. |
Get Reviews Count
Account Method
Get Reviews Count
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 141;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/' . $reportId . '/reviews/count');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf/141/reviews/count?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId = 141;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic response = api.Get("v4/rf/" + reportId + "/reviews/count").GetContent();
Console.WriteLine(response);
Success (200 OK)
{
"success": true,
"count": "2770"
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID missing"
}
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>/reviews/count
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Get Growth
Account Method
Get Growth
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 141;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/' . $reportId . '/reviews/growth');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf/141/reviews/growth?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId = 1;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic grows = api.Get("v4/rf/{reportId}/reviews/growth").GetContent();
Console.WriteLine(grows);
Get count and percentage of new reviews since last report run.
Success (200 OK)
{
"success": true,
"growth": {
"number": "1",
"percent": "0.03"
}
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID missing"
}
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>/reviews/growth
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Get Directories
Account Method
Get Directories
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 141;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/' . $reportId . '/directories');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf/141/directories?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId = 141;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic directories = api.Get("v4/rf/" + reportId + "/directories").GetContent();
Console.WriteLine(directories);
Success (200 OK)
{
"success": true,
"directories": {
"citysearch": {
"directory": "citysearch",
"name": "Citysearch",
"use": true,
"url": "http://www.citysearch.com/profile/612944020/los_angeles_ca/pizzeria_mozza.html",
"searched": true,
"reviews": 117
},
"dexknows": {
"directory": "dexknows",
"name": "DexKnows",
"use": true,
"url": "http://www.dexknows.com/business_profiles/pizzeria_mozza_los_angeles-l900211841",
"searched": true,
"reviews": 0
},
"google": {
"directory": "google",
"name": "Google+ Local",
"use": true,
"url": "https://plus.google.com/116883746235536288122/about?hl=en&rfmt=s",
"searched": true,
"reviews": 145
},
"insiderpages": {
"directory": "insiderpages",
"name": "Insider Pages",
"use": true,
"url": "http://www.insiderpages.com/b/15240159890/pizzeria-mozza-los-angeles",
"searched": true,
"reviews": 5
},
"judysbook": {
"directory": "judysbook",
"name": "Judy's Book",
"use": true,
"url": "http://www.judysbook.com/Pizzeria-Mozza-Restaurants-losangeles-r26871385.htm",
"searched": true,
"reviews": 127
},
"kudzu": {
"directory": "kudzu",
"name": "Kudzu",
"use": true,
"url": "http://www.kudzu.com/m/Pizzeria-Mozza-20924094",
"searched": true,
"reviews": 117
},
"localcom": {
"directory": "localcom",
"name": "Local.com",
"use": true,
"url": "http://www.local.com/business/details/los-angeles-ca/mozza-cafe-105106399/",
"searched": true,
"reviews": 1
},
"manta": {
"directory": "manta",
"name": "Manta",
"use": true,
"url": "http://www.manta.com/c/mrsy0q6/falbo-bros-pizzeria",
"searched": true,
"reviews": 0
},
"merchantcircle": {
"directory": "merchantcircle",
"name": "Merchant Circle",
"use": true,
"url": "http://www.merchantcircle.com/business/Pizzeria.Mozza.323-297-0101",
"searched": true,
"reviews": 42
},
"superpages": {
"directory": "superpages",
"name": "Super Pages",
"use": true,
"url": "http://www.superpages.com/bp/Los-Angeles-CA/Pizzeria-Mozza-L0136883359.htm",
"searched": true,
"reviews": 3
},
"yahoo": {
"directory": "yahoo",
"name": "Yahoo! Local",
"use": true,
"url": "http://local.yahoo.com/info-36089572-pizzeria-mozza-los-angeles;_ylt=A0oG7hXne95SMD4AyqhXNyoA;_ylu=X3oDMTBybnZlZnRlBHNlYwNzcgRwb3MDMQRjb2xvA2FjMgR2dGlkAw--",
"searched": true,
"reviews": 2
},
"yellowbot": {
"directory": "yellowbot",
"name": "Yellow Bot",
"use": true,
"url": "http://www.yellowbot.com/pizzeria-mozza-los-angeles-ca.html",
"searched": true,
"reviews": 324
},
"yellowpages": {
"directory": "yellowpages",
"name": "Yellow Pages",
"use": true,
"url": "http://www.yellowpages.com/los-angeles-ca/mip/pizzeria-mozza-18463301",
"searched": true,
"reviews": 108
},
"yelp": {
"directory": "yelp",
"name": "Yelp",
"use": true,
"url": "http://www.yelp.com/biz/pizzeria-mozza-los-angeles",
"searched": true,
"reviews": 2966
}
}
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID missing"
}
}
Get a list of directories associated with a report. Results contain directory details, profile URLs and review counts.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>/directories
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Get Directory Stats
Account Method
Fetch stats showing average rating and review count for every directory in a given report.
Get Directory Stats
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 141;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/' . $reportId . '/directories/stats');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf/141/directories/stats?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId = 141;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic response = api.Get("v4/rf/{reportId}/directories/stats").GetContent();
Console.WriteLine(response);
Success (200 OK)
{
"success": true,
"stats": {
"botw": {
"directory": "botw",
"name": "Best of the Web",
"use": true,
"url": "http://local.botw.org/New_York/New_York/Ayza/1000053931.html",
"searched": true,
"rating": 0,
"reviews": 0
},
"citysearch": {
"directory": "citysearch",
"name": "Citysearch",
"use": true,
"url": "http://www.citysearch.com/profile/7143737/new_york_ny/le_bernardin.html",
"searched": true,
"rating": "4.00",
"reviews": 91
},
"foursquare": {
"directory": "foursquare",
"name": "FourSquare",
"use": true,
"url": "https://foursquare.com/v/le-bernardin-new-york-ny/3fd66200f964a52066e31ee3",
"searched": true,
"rating": "0.00",
"reviews": 190
}
}
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID missing"
}
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>/directories/stats
Fetch stats showing average rating and review count for every directory in a given report.
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Get Star Counts
Account Method
Get Start Counts
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 141;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/rf/' . $reportId . '/stars/count');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/rf/141/stars/count?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId =141;
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
dynamic response = api.Get("v4/rf/" + reportId + "/stars/count").GetContent();
Console.WriteLine(response);
Success (200 OK)
{
"success": true,
"counts": {
"0star": "91",
"1star": "223",
"2star": "180",
"3star": "394",
"4star": "704",
"5star": "1178"
}
}
Validation Failure 400 Bad Request
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID missing"
}
}
Get count of reviews for each star rating for a given report.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/rf/<reportId>/stars/count
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Google My Business
Add Report
Account Method
Add Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v4/gpw/add', [
'location_id' => 1,
'schedule' => 'Adhoc',
'day_of_month' => '2',
'report_type' => 'with',
'google_location' => 'New York, NY',
'search_terms' => '["restaurant manhattan","cafe new york"]'
]);
print_r($response->getResult());
curl -X POST \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'location_id=1' \
-d 'schedule=Adhoc' \
-d 'day_of_month=2' \
-d 'report_type=with' \
-d 'search_terms=["restaurant manhattan","cafe new york"]'
https://tools.brightlocal.com/seo-tools/api/v4/gpw/add
Api api = new Api(apiKey, apiSecret);
Parameters parameters = new Parameters
{
{ "location_id", 1 },
{ "schedule", "Adhoc" },
{ "day_of_month", "2" },
{ "report_type", "with" },
{ "google_location", "New York, NY" },
{ "search_terms", new List<string> { "restaurant manhattan", "cafe new york" } },
};
Response response = api.Post("/v4/gpw/add", parameters);
Console.WriteLine(response.GetContent());
Success (201 Created)
{
"success": true,
"report-id": "1"
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"run": "You don\'t have any credits left",
"report_type": "Report type is not available",
"search_terms": "Please enter at least one search term",
"google_location": "The location was not recognized. Please enter a correct location",
"schedule": "Please select schedule"
}
}
Adds a new Google My Business report to your account.
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/gpw/add
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| report_name | Deprecated, please use Location for update this field. |
| location_id | Required Associate this report with a location in your account. This ID needs to correspond to a valid location in your account. |
| white_label_profile_id | Deprecated, please use Location for update this field. |
| business_names | Deprecated, please use Location for update this field. |
| schedule | Required One of Adhoc or Monthly |
| day_of_month | Required One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, -1 (last day of month). |
| report_type | Required One of with or without. ‘with’ - the business has a Google Local profile. 'without’ - Ignore this business, just display competitor information. Defaults to with. |
| address1 | Deprecated, please use Location for update this field. |
| address2 | Deprecated, please use Location for update this field. |
| city | Deprecated, please use Location for update this field. |
| state_code | Deprecated, please use Location for update this field. |
| google_location | Required A valid google search location. Please refer to our location check method. |
| is_public | Deprecated, please use Location for update this field. |
| postcode | Deprecated, please use Location for update this field. |
| phone_number | Deprecated, please use Location for update this field. |
| country | Deprecated, please use Location for update this field. |
| search_terms | Required Supply one or more search terms (max 5) as a JSON string. For example, [“restaurant san francisco”,“cafe san francisco”]. |
| notify | One of Yes or No. If set to yes we will send report alerts to all email addresses specified (see field below). If you include customer email addresses when setting up your report we’ll also email them the alerts so please be sure this is what you want before adding their addresses. Default is No. |
| email_addresses | Supply one or more (max 5) email addresses for us to send report alerts to. This only takes effect if notify is set to Yes. JSON string. For example, [“email1@test.com”,“email2@test.com”]. |
| run | One of Yes or No. Runs the report after adding. Defaults to Yes. |
Update Report
Account Method
Update Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->put('/v4/gpw/' . $reportId, [
'location-id' => 1,
'schedule' => 'Adhoc'
]);
print_r($response->getResult());
curl -X PUT \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'location_id=1' \
-d 'schedule=Adhoc' \
-d 'day_of_month=2' \
https://tools.brightlocal.com/seo-tools/api/v4/gpw/1
int reportId = 1;
Api api = new Api(apiKey, apiSecret);
Parameters parameters = new Parameters
{
{ "location-id", 1 },
{ "schedule", "Adhoc" },
};
Response response = api.Put("/v4/gpw/"+ reportId, parameters);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID": "Report ID invalid"
}
}
HTTP Request
PUT https://tools.brightlocal.com/seo-tools/api/v4/gpw/<reportId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| report-ID | Required |
| report_name | Deprecated, please use Location for update this field. |
| location_id | Required Associate this report with a location in your account. This ID needs to correspond to a valid location in your account. |
| white_label_profile_id | Deprecated, please use Location for update this field. |
| business_names | Deprecated, please use Location for update this field. |
| schedule | One of Adhoc or Monthly |
| day_of_month | One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, -1 (last day of month). |
| report_type | One of with or without. 'with’ - the business has a Google Local profile. 'without’ - Ignore this business, just display competitor information. Defaults to with. |
| address1 | Deprecated, please use Location for update this field. |
| address2 | Deprecated, please use Location for update this field. |
| city | Deprecated, please use Location for update this field. |
| state_code | Deprecated, please use Location for update this field. |
| postcode | Deprecated, please use Location for update this field. |
| phone_number | Deprecated, please use Location for update this field. |
| country | Deprecated, please use Location for update this field. |
| search_terms | Supply one or more search terms (max 5) as a JSON string. For example, [“restaurant san francisco”,“cafe san francisco”]. |
| notify | One of Yes or No. If set to yes we will send report alerts to all email addresses specified (see field below). If you include customer email addresses when setting up your report we’ll also email them the alerts so please be sure this is what you want before adding their addresses. Default is No. |
| email_addresses | Supply one or more (max 5) email addresses for us to send report alerts to. This only takes effect if notify is set to Yes. JSON string. For example, [“email1@test.com”,“email2@test.com”]. |
| google_location | A valid google search location. Please refer to our location check method. |
| is_public | Deprecated, please use Location for update this field. |
| run | One of Yes or No. Runs the report after adding. Defaults to Yes. |
Get Report
Account Method
Get Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/gpw/' . $reportId);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/gpw/1?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId = 1;
Api api = new Api(apiKey, apiSecret);
Response response = api.Get("v4/gpw/" + reportId);
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"report": {
"report_id": "1",
"report_name": "Report name",
"customer_id": "1",
"location_id": "1000",
"schedule": "Adhoc",
"day_of_week": "0",
"day_of_month": "0",
"white_label_profile_id": "24",
"report_type": "without",
"business_names": [
"Business name1"
],
"postcode": "90210",
"country": "USA",
"state_code": "IL",
"address1": "email@test.com",
"address2": null,
"city": "Chicago, IL",
"phone_number": null,
"search_terms": [
"search_term1",
"search_term2",
"search_term3"
],
"google_location": "Chicago, IL",
"notify": "Yes",
"email_addresses": [
"email@company.com"
],
"notify_about_changes": true,
"email_addresses_for_changes": [
"email@company.com"
],
"is_public": "Yes",
"public_key": "<hidden>",
"is_running": "No"
}
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID invalid"
}
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/gpw/<reportId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Delete Report
Account Method
Delete Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->delete('/v4/gpw/' . $reportId);
var_dump($response->getResult());
if ($response->isSuccess()) {
echo 'Successfully deleted report.' . PHP_EOL;
}
curl -X DELETE \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
https://tools.brightlocal.com/seo-tools/api/v4/gpw/1
int reportId = 1;
Api api = new Api(apiKey, apiSecret);
Response response = api.Delete("/v4/gpw/" + reportId);
if (response.IsSuccess())
{
Console.WriteLine("Successfully deleted report.");
}
else
{
Console.WriteLine(response.GetContent());
}
Success (200 OK)
{
"success": true
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID": "Report ID invalid"
}
}
HTTP Request
DELETE https://tools.brightlocal.com/seo-tools/api/v4/gpw/<reportId>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Get All Reports
Account Method
Get All Reports
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/gpw/');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/gpw?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
Api api = new Api(apiKey, apiSecret);
Response response = api.Get("/v4/gpw/");
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"response": {
"results": [
{
"report_id": "49",
"report_name": "Test 1",
"schedule": "Weekly",
"is_running": "Yes",
"running_message": "Identifying your top Google Local competitors"
},
{
"report_id": "50",
"report_name": "Test 2",
"schedule": "Monthly",
"is_running": "No",
"running_message": ""
}
]
}
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_LOCATION_ID": "Invalid location ID supplied"
}
}
Returns basic details about all reports associated with your account.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/gpw
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| location-id |
Run Report
Account Method
Run Report
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->post('/v4/gpw/run', [
'report-id' => 860
]);
print_r($response->getResult());
curl -X PUT \
-d 'api-key=<INSERT_API_KEY>' \
-d 'sig=<INSERT_API_SIG>' \
-d 'expires=<INSERT_API_EXPIRES>' \
-d 'report-id=860' \
https://tools.brightlocal.com/seo-tools/api/v4/gpw/run
int reportId = 860;
Api api = new Api(apiKey, apiSecret);
Response response = api.Put("/v4/gpw/run", new Parameters { ["report-id"] = reportId });
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_REPORT_ID" : "Report ID missing",
"NO_CREDITS" : "You don't have any credits left"
}
}
Failure when report already running (400 Bad Request)
{
"success": false,
"errors": {
"REPORT_RUNNING": "Report is already running"
}
}
HTTP Request
POST https://tools.brightlocal.com/seo-tools/api/v4/gpw/run
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
| report-id | Required The unique ID for the report in your account. |
Get Report Results
Account Method
Get Report Results
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$reportId = 1;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v4/gpw/' . $reportId . '/results');
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v4/gpw/1/results?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
int reportId =1;
Api api = new Api(apiKey, apiSecret);
Response response = api.Get("/v4/gpw/" + reportId + "/results");
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"results": {
"summary": {
"business_name": "Iron Galaxy Studios LLC",
"address": "300 E Colorado Blvd, Pasadena, CA 91101, United States",
"telephone": "+1 123-456-7890",
"website_address": "http://www.example.com",
"opening_hours": [
"Wednesday 4PM–1AM",
"Thursday 4PM–1AM",
"Friday 4PM–1AM",
"Saturday 4PM–1AM",
"Sunday(Easter) 4PM–1AM Hours might differ",
"Monday 4PM–1AM",
"Tuesday 4PM–1AM"
],
"profile_url": "https://www.google.co.uk/search?q=Iron+Galaxy+Studios+LLC&oq=Iron+Galaxy+Studios+LLC",
"claimed": false,
"citations_count": 74,
"domain_authority": 37.65,
"backlinks": 1395,
"num_reviews": 6,
"star_rating": 4,
"review_content": "The Hotel is very conveniently located and the room nice",
"num_photos": 0,
"categories": [
"Financial Planner"
]
},
"keywords": {
"iron": {
"client_rank": 1,
"top_10": [
{
"business_name": "Iron Galaxy Studios LLC",
"rank": "A",
"client_business": true,
"profile_url": "https://www.google.co.uk/search?q=Iron+Galaxy+Studios+LLC&oq=Iron+Galaxy+Studios+LLC",
"claimed": false,
"citations_count": 74,
"domain_authority": "37/100",
"backlinks": 1395,
"num_reviews": 4,
"star_rating": "5/5",
"num_photos": 0,
"categories": [
"Hotel"
]
},
{
"business_name": "Iron Financial Management Inc",
"rank": "B",
"client_business": false,
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&q=Iron+Financial+Management+Inc",
"claimed": false,
"citations_count": 118,
"domain_authority": "22/100",
"backlinks": 86,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 0,
"categories": [
"Financial Planner"
]
},
{
"business_name": "Chicago Tube and Iron Company",
"rank": "C",
"client_business": false,
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&q=Chicago+Tube+and+Iron+Company+Chicago",
"claimed": false,
"citations_count": 106,
"domain_authority": "30/100",
"backlinks": 190,
"num_reviews": 2,
"star_rating": "1/5",
"num_photos": 0,
"categories": [
"Hotel",
"Hotel",
"Hotel",
"Hotel"
]
},
{
"business_name": "Acorn Wire & Iron Works LLC",
"rank": "D",
"client_business": false,
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&gbv=2&q=Acorn+Wire+%26+Iron+Works+LLC%2C+chicago",
"claimed": false,
"citations_count": 56,
"domain_authority": "29/100",
"backlinks": 80,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 1,
"categories": [
"Fence Supply Store"
]
},
{
"business_name": "Iron & Wire Custom Metal Studio LLC",
"rank": "E",
"client_business": false,
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&gbv=2&q=Iron+%26+Wire+Custom+Metal+Studio+LLC%2C+chicago",
"claimed": true,
"citations_count": 25,
"domain_authority": "18/100",
"backlinks": 18,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 2,
"categories": [
"Metal Fabricator",
"Interior Designer",
"Steel Fabricator"
]
},
{
"business_name": "Adams Street Iron Inc",
"rank": "F",
"client_business": false,
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&biw=1277&bih=573&q=Adams+Street+Iron+Inc%2C+Chicago",
"claimed": false,
"citations_count": 66,
"domain_authority": "10/100",
"backlinks": 7,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 0,
"categories": [
"Hotel",
"General Contractor"
]
},
{
"business_name": "Iron Workers Union",
"rank": "G",
"client_business": false,
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&gbv=2&q=Iron+Workers+Union%2C+chicago+60130",
"claimed": false,
"citations_count": 39,
"domain_authority": "48/100",
"backlinks": 5037,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 0,
"categories": [
"Hotel",
"Non-Profit Organization"
]
},
{
"business_name": "Shaw Environmental/Infrstrctr",
"rank": "H",
"client_business": false,
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&gbv=2&q=Shaw+Environmental%2FInfrstrctr%2C+chicago",
"claimed": false,
"citations_count": 52,
"domain_authority": "60/100",
"backlinks": 8884,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 0,
"categories": [
"Hotel"
]
}
],
"citations_matrix": [
{
"domain": "facebook.com",
"authority": "100/100",
"count": 5,
"businesses": [
{
"business_name": "Iron Galaxy Studios LLC",
"citations_count": "74",
"url": "https://www.facebook.com/103101903089752"
},
{
"business_name": "Iron Financial Management Inc",
"citations_count": "118",
"url": null
},
{
"business_name": "Chicago Tube and Iron Company",
"citations_count": "106",
"url": "https://www.facebook.com/pages/Law-Offices-of-Bernard-D-Ward-PC-708-349-5600-815-834-2000/143994815665091"
},
{
"business_name": "Acorn Wire & Iron Works LLC",
"citations_count": "56",
"url": null
},
{
"business_name": "Iron & Wire Custom Metal Studio LLC",
"citations_count": "25",
"url": "https://www.facebook.com/pages/Iron-Wire/104803202926726?sk=info"
},
{
"business_name": "Adams Street Iron Inc",
"citations_count": "66",
"url": "https://www.facebook.com/pages/Adams-Street-Iron/117016575024837"
},
{
"business_name": "Iron Workers Union",
"citations_count": "39",
"url": null
},
{
"business_name": "Shaw Environmental/Infrstrctr",
"citations_count": "52",
"url": "https://www.facebook.com/pages/International-Technology-Corp/154765177895978"
}
]
},
{
"domain": "linkedin.com",
"authority": "100/100",
"count": 2,
"businesses": [
{
"business_name": "Iron Galaxy Studios LLC",
"citations_count": "74",
"url": "https://www.linkedin.com/in/michaelpickens"
},
{
"business_name": "Iron Financial Management Inc",
"citations_count": "118",
"url": "https://www.linkedin.com/pub/miles-muslin/18/287/950"
},
{
"business_name": "Chicago Tube and Iron Company",
"citations_count": "106",
"url": null
},
{
"business_name": "Acorn Wire & Iron Works LLC",
"citations_count": "56",
"url": null
},
{
"business_name": "Iron & Wire Custom Metal Studio LLC",
"citations_count": "25",
"url": null
},
{
"business_name": "Adams Street Iron Inc",
"citations_count": "66",
"url": null
},
{
"business_name": "Iron Workers Union",
"citations_count": "39",
"url": null
},
{
"business_name": "Shaw Environmental/Infrstrctr",
"citations_count": "52",
"url": null
}
]
}
],
"nap_comparison": [
{
"taken_from": "User supplied",
"business_name": "Example & Co",
"address": "email@example.com Chicago, IL IL",
"postcode": "90210",
"telephone": "4234324234"
},
{
"taken_from": "Google Listing",
"business_name": null,
"address": "",
"postcode": null,
"telephone": null
}
],
"top_categories": {
"Hotel": 8,
"General Contractor": 1,
"Non-Profit Organization": 1,
"Steel Fabricator": 1,
"Metal Fabricator": 1
},
"other_ranking_factors": []
},
"gold": {
"top_10": [
{
"business_name": "Gold Eagle",
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&site=&source=hp&q=gold+eagle+chicago",
"claimed": true,
"citations_count": 62,
"domain_authority": "45/100",
"backlinks": 9918,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 0,
"categories": [
"Shipping Company"
]
},
{
"business_name": "Rickey Gold Associates",
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&q=Rickey+Gold+Associates",
"claimed": false,
"citations_count": 96,
"domain_authority": "26/100",
"backlinks": 57,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 0,
"categories": [
"Marketing Consultant"
]
},
{
"business_name": "Bentley Gold Coast",
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&q=Bentley+Gold+Coast%2C+Chicago&oq=Bentley+Gold+Coast%2C+Chicago",
"claimed": false,
"citations_count": 89,
"domain_authority": "32/100",
"backlinks": 87,
"num_reviews": 58,
"star_rating": "4.2/5",
"num_photos": 5,
"categories": [
"Car Dealer"
]
},
{
"business_name": "Gold Coast Tickets",
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&q=Gold+Coast+Tickets%2C+Chicago",
"claimed": false,
"citations_count": 47,
"domain_authority": "34/100",
"backlinks": 1362,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 0,
"categories": [
"Event Ticket Seller"
]
},
{
"business_name": "Gold Canyon Candles",
"profile_url": "https://www.google.co.uk/search?newwindow=1&safe=active&q=Gold+Canyon+Candles%2C+Schaumburg%2C+IL+60193",
"claimed": true,
"citations_count": 19,
"domain_authority": "n/a",
"backlinks": 0,
"num_reviews": 0,
"star_rating": "0/5",
"num_photos": 0,
"categories": [
"Gift Basket Store",
"Hotel"
]
}
],
"citations_matrix": [
{
"domain": "facebook.com",
"authority": "100/100",
"count": 6,
"businesses": [
{
"business_name": "Iron Galaxy Studios LLC",
"citations_count": "74",
"url": "https://www.facebook.com/103101903089752"
},
{
"business_name": "Iron Financial Management Inc",
"citations_count": "118",
"url": null
},
{
"business_name": "Chicago Tube and Iron Company",
"citations_count": "106",
"url": "https://www.facebook.com/pages/Law-Offices-of-Bernard-D-Ward-PC-708-349-5600-815-834-2000/143994815665091"
},
{
"business_name": "Acorn Wire & Iron Works LLC",
"citations_count": "56",
"url": null
},
{
"business_name": "Iron & Wire Custom Metal Studio LLC",
"citations_count": "25",
"url": "https://www.facebook.com/pages/Iron-Wire/104803202926726?sk=info"
},
{
"business_name": "Adams Street Iron Inc",
"citations_count": "66",
"url": "https://www.facebook.com/pages/Adams-Street-Iron/117016575024837"
},
{
"business_name": "Iron Workers Union",
"citations_count": "39",
"url": null
},
{
"business_name": "Shaw Environmental/Infrstrctr",
"citations_count": "52",
"url": "https://www.facebook.com/pages/International-Technology-Corp/154765177895978"
},
{
"business_name": "Gold Eagle",
"citations_count": "62",
"url": null
},
{
"business_name": "Rickey Gold Associates",
"citations_count": "96",
"url": null
},
{
"business_name": "Bentley Gold Coast",
"citations_count": "89",
"url": "https://www.facebook.com/pages/Bentley-Gold-Coast/135572886504845"
},
{
"business_name": "Gold Coast Tickets",
"citations_count": "47",
"url": null
},
{
"business_name": "Gold Canyon Candles",
"citations_count": "19",
"url": null
}
]
},
{
"domain": "linkedin.com",
"authority": "100/100",
"count": 2,
"businesses": [
{
"business_name": "Iron Galaxy Studios LLC",
"citations_count": "74",
"url": "https://www.linkedin.com/in/michaelpickens"
},
{
"business_name": "Iron Financial Management Inc",
"citations_count": "118",
"url": "https://www.linkedin.com/pub/miles-muslin/18/287/950"
},
{
"business_name": "Chicago Tube and Iron Company",
"citations_count": "106",
"url": null
},
{
"business_name": "Acorn Wire & Iron Works LLC",
"citations_count": "56",
"url": null
},
{
"business_name": "Iron & Wire Custom Metal Studio LLC",
"citations_count": "25",
"url": null
},
{
"business_name": "Adams Street Iron Inc",
"citations_count": "66",
"url": null
},
{
"business_name": "Iron Workers Union",
"citations_count": "39",
"url": null
},
{
"business_name": "Shaw Environmental/Infrstrctr",
"citations_count": "52",
"url": null
},
{
"business_name": "Gold Eagle",
"citations_count": "62",
"url": null
},
{
"business_name": "Rickey Gold Associates",
"citations_count": "96",
"url": null
},
{
"business_name": "Bentley Gold Coast",
"citations_count": "89",
"url": null
},
{
"business_name": "Gold Coast Tickets",
"citations_count": "47",
"url": null
},
{
"business_name": "Gold Canyon Candles",
"citations_count": "19",
"url": null
}
]
}
],
"nap_comparison": [
{
"taken_from": "User supplied",
"business_name": "Example & Co",
"address": "email@example.com Chicago, IL IL",
"postcode": "85300",
"telephone": "4234324234"
},
{
"taken_from": "Google Listing",
"business_name": null,
"address": "",
"postcode": null,
"telephone": null
}
],
"top_categories": {
"Gift Basket Store": 1,
"Hotel": 1,
"Event Ticket Seller": 1,
"Car Dealer": 1,
"Marketing Consultant": 1
},
"other_ranking_factors": []
}
},
"urls": {
"report_url": "https://tools.brightlocal.com/seo-tools/admin/gpw/reports/view/275",
"wl_url": "http://local-marketing-reports.com/google-plus-reports/<hidden>/275"
}
}
}
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_LOCATION_ID": "Invalid location ID supplied"
}
}
Return report URLs and raw data.
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v4/gpw/<reportId>/results
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Business Categories
Fetch Business Categories (deprecated)
Account Method
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$country = 'USA';
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$response = $api->get('/v1/business-categories/' . $country);
print_r($response->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v1/business-categories/USA?api-key=<INSERT_API_KEY>'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
string country = "USA";
Response response = api.Get("/v1/business-categories/" + country);
Console.WriteLine(response.GetContent());
Success (200 OK)
[
{
"id": 503,
"name": "Advertising Agency"
}
]
Validation Failure (400 Bad Request)
{
"success": false,
"errors": {
"INVALID_COUNTRY": "Country is not supported"
}
}
HTTP Request
Get all business categories for certain country. See here for a full list of supported countries.
GET https://tools.brightlocal.com/seo-tools/api/v1/business-categories/<country>
Appendix
Supported Local Directories
We now have an API method (shown below) that enables you to retrieve a list of directories for all supported countries.
Get list of supported local directories (deprecated)
Account Method
Get list of supported local directories
<?php
require '../../vendor/autoload.php';
use BrightLocal\Api;
$api = new Api('<YOUR_API_KEY>', '<YOUR_API_SECRET>');
$responseForAll = $api->get('v1/directories/all');
print_r($responseForAll->getResult());
$country = 'USA';
$responseByCountry = $api->get('v1/directories/' . $country);
print_r($responseByCountry->getResult());
curl -X GET 'https://tools.brightlocal.com/seo-tools/api/v1/directories/all?api-key=<INSERT_API_KEY>&sig=<INSERT_API_SIG>&expires=<INSERT_API_EXPIRES>'
Api api = new Api("<INSERT_API_KEY>", "<INSERT_API_SECRET>");
Response response = api.Get("v1/directories/all" );
Console.WriteLine(response.GetContent());
Success (200 OK)
{
"success": true,
"count": 375,
"supported_countries": ["GBR","USA","IRL",...],
"results": [
{
"identifier": "google",
"countries": ["GBR","USA"],
"url":"google.com",
"urls":[
{"USA": "google.com"},
{"GBR": "google.uk"},...
],
"supports_reviews": true
},...
]
}
HTTP Request
GET https://tools.brightlocal.com/seo-tools/api/v1/directories/all
GET https://tools.brightlocal.com/seo-tools/api/v1/directories/<country>
Query Parameters
| Parameter | Notes |
|---|---|
| api-key | Required |
| sig | Required See above for how to generate signature and expires values. |
| expires | Required See above for how to generate signature and expires values. |
Local directories supported by Local Search Audit tool
USA
| Directory | Identifier |
|---|---|
| Brownbook | brownbook |
| Citysearch | citysearch |
| DexKnows | dexknows |
| Factual | factual |
| FourSquare | foursquare |
| Google Local | |
| HotFrog | hotfrog |
| InfoUSA/ExpressUpdate | expressupdate |
| Insider Pages | insiderpages |
| Kudzu | kudzu |
| Local.com | localcom |
| MapQuest | mapquest |
| Neustarlocaleze | neustarlocaleze |
| Super Pages | superpages |
| Yahoo! Local | yahoo |
| Yellow Bot | yellowbot |
| Yellow Pages | yellowpages |
| Yelp | yelp |
Canada
| Directory | Identifier |
|---|---|
| 411 Canada | can411 |
| Brownbook | brownbook |
| Canpages | canpages |
| Factual | factual |
| FourSquare | foursquare |
| Google Local | |
| HotFrog | hotfrog |
| iBegin | ibegincan |
| PagesJunes | pagesjaunes |
| Yellow Pages | yellowpagesca |
| Yelp | yelp |
United Kingdom
| Directory | Identifier |
|---|---|
| Brownbook | brownbook |
| Factual | factual |
| FourSquare | foursquare |
| Google Local | |
| HotFrog | hotfrog |
| Scoot | scoot |
| Thomson Local | thomsonlocal |
| Touch Local | touchlocal |
| Yahoo! Local | yahoo |
| Yell | yell |
| Yelp | yelp |
Australia
| Directory | Identifier |
|---|---|
| AussieWeb | aussieweb |
| Brownbook | brownbook |
| dLook | dlook |
| Factual | factual |
| FourSquare | foursquare |
| Google Local | |
| HotFrog | hotfrog |
| Local.com.au | localcomau |
| StartLocal | startlocal |
| Super Pages Australia | superpagesaus |
| TrueLocal | truelocal |
| White Pages | whitepagesaus |
| Yelp | yelp |
Business Category IDs
We no longer list the supported business categories here. We now have an endpoint which enables you to retrieve a list of categories by country.
Supported Countries
The following countries and codes are supported by our system:
| Country | Code |
|---|---|
| Australia | AUS |
| Canada | CAN |
| Germany | DEU |
| Hong Kong | HKG |
| Ireland | IRL |
| Macau | MAC |
| Netherlands | NLD |
| New Zealand | NZL |
| Philippines | PHL |
| Taiwan | TWN |
| United Kingdom | GBR |
| United States | USA |
| Singapore | SGP |
| South Africa | ZAF |