Introduction
Welcome to the Nightwatch API docs! Here you can find guides on how to interact with data associated with your Nightwatch account using HTTP requests (REST API).
If you don't have an account yet, sign up for a Nightwatch account.
API Access is enabled on Nightwatch Pro plans only.
Authentication
Nightwatch API uses access_token
authentication. You need to provide your access_token
URL parameter for all requests you issue against our API.
https://api.nightwatch.io/some_action?access_token=ACCESS_TOKEN
Access Token
Obtain an access token for your user
curl 'https://api.nightwatch.io/api/v1/token' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"email": "YOUR_EMAIL", "password": "YOUR_PASSWORD"}
The above command returns JSON structured like this:
{
"access_token": "TOKEN"
}
This endpoint gets you the access token that you must include with all your requests.
HTTP Request
POST https://api.nightwatch.io/api/v1/token
Body Parameters
Parameter | Description |
---|---|
Your Nightwatch e-mail | |
password | Your Nightwatch password |
User
This endpoint deals with the current user data. If you want to manage users under your account (add, remove subusers or change their permissions), head over to the subusers section.
Get user
curl 'https://api.nightwatch.io/api/v1/user?access_token=ACCESS_TOKEN' \
-H 'Content-Type: application/json'
HTTP Request
GET https://api.nightwatch.io/api/v1/user?access_token=ACCESS_TOKEN
Available fields:
Field | Description |
---|---|
id | User's internal ID |
name | User's name |
report_interval | Summary report interval (in seconds) |
report_hour | Hour of the summary report |
payment_active | Whether or not the paid subscription is active |
plan | Info about the subscription plan |
account_access | Info about the current user account access |
keyword_limit | Keyword limit |
url_limit | URL limit |
backlinks_limit | Backlinks limit |
timezone | User's timezone |
whitelabel | Whether or not the account is whitelabeled |
agency | Whether or not the account is whitelabeled |
invoice_email | Email used on the invoice |
invoice_name | Name used on the invoice |
invoice_address | Address used on the invoice |
invoice_state | State used on the invoice |
invoice_city | City used on the invoice |
invoice_postcode | Postcode used on the invoice |
invoice_country | Country used on the invoice |
invoice_vat_number | Country used on the invoice |
is_company | Whether or not the account is a company |
credits | How many Partner API credits the account has |
status | Account status (trial, expired, paying, subuser, cancelled) |
active_until | Until when the subscription is good for (this extends on every billing cycle) |
next_payment_due_on | Date of next billing |
keywords_remaining | Keywords remaining until limit is reached |
urls_remaining | URLs remaining until limit is reached |
keyword_count | Keywords used |
url_count | URLs used |
last_login_ip | Last login IP |
Update user
curl 'https://api.nightwatch.io/api/v1/user?access_token=ACCESS_TOKEN' \
-H 'Content-Type: application/json'
HTTP Request
PUT https://api.nightwatch.io/api/v1/user?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
name | Name |
password | Password |
timezone | Timezone in TZ database name format |
report_interval | Summary report interval in seconds (available options: 86400, 604800, 2592000) |
invoice_email | Email for invoices |
invoice_name | Name on the invoice |
invoice_address | Address on the invoice |
invoice_state | State on the invoice |
invoice_city | City on the invoice |
invoice_postcode | Postcode on the invoice |
invoice_country | Postcode on the invoice (Full name format, e.g New Zealand) |
invoice_vat_number | Company's VAT number |
is_company | Is the account a company (needed for VAT exempt: true/false) |
Subusers
Besides the main account with which a Nightwatch account was created, accounts
can also have a number of users that can access its data or just part of it.
These are called subusers, and there are two kinds: admin
and limited
. Admin
users can access every aspect of an account, including invoicing, billing
settings, and subuser administration. Limited subusers can only access URL
groups they've been granted access to. Additionally, permissions can be granted
to limited subusers to create new keywords and URLs.
A third special class of subusers is owner
, there is only one of this kind,
and it's a read-only property, that is, another subuser cannot be made owner.
Owner subusers are an account's registration users. Onwers cannot be deleted, to
switch the owner of an account you need to contact support.
Subusers data
Field | Description |
---|---|
id | Subuser ID |
Subuser email | |
access_type | Whether this is an "admin" or "limited" subuser |
owner | Whether this subuser is the owner of the account |
adding_keywords | Whether this user can create new keywords |
adding_urls | Whether this user can create new URLs |
group_ids | URL groups' IDs this subuser has access to |
keyword_limit | Number of keywords this subuser can create |
keyword_limit_enabled | Whether keywords limit is enabled |
url_limit | Number of URLs this subuser can create |
url_limit_enabled | Whether URLs limit is enabled |
last_access | Last time this user logged in |
last_login_ip | Last IP address this subuser logged in from |
created | When this user was created |
List subusers
curl 'https://api.nightwatch.io/api/v1/subusers?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"id": 100,
"access_type": "admin",
"adding_keywords": true,
"adding_urls": true,
"created": "about 6 years ago",
"email": "[email protected]",
"group_ids": [],
"keyword_limit": 0,
"keyword_limit_enabled": false,
"last_access": "3 minutes ago",
"last_login_ip": "127.0.0.1",
"owner": true,
"url_limit": 0,
"url_limit_enabled": false
},
...
]
HTTP Request
GET https://api.nightwatch.io/api/v1/subusers/keywords?access_token=ACCESS_TOKEN
Get a subuser
curl 'https://api.nightwatch.io/api/v1/subusers/SUBUSER_ID?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"id": 101,
"access_type": "limited",
"email": "[email protected]",
"group_ids": [100, 101, 102],
"adding_keywords": true,
"adding_urls": true,
"keyword_limit": 10,
"keyword_limit_enabled": true,
"url_limit": 10,
"url_limit_enabled": true
}
HTTP Request
POST https://api.nightwatch.io/api/v1/subusers/SUBUSER_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
subuser_id* | Subuser ID to fetch |
Create a subuser
After creating a subuser, the system will send an email to the address provided with a confirmation link. This link will redirect the user to a page where they can set their password, and confirm the registration. Only after this process is completed the subuser account can be used.
curl 'https://api.nightwatch.io/api/v1/subusers?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json' \\
-X POST \\
-d '{
"subuser": {
"access_type": "limited",
"email": "[email protected]",
"group_ids": [100, 101, 102],
"adding_keywords": true,
"adding_urls": true,
"keyword_limit": 10,
"keyword_limit_enabled": true,
"url_limit": 10,
"url_limit_enabled": true,
"created": "less than a minute ago",
"last_access": null,
"last_login_ip": ""
}
}'
The above command returns JSON structured like this:
{
"id": 101,
"access_type": "limited",
"email": "[email protected]",
"group_ids": [100, 101, 102],
"adding_keywords": true,
"adding_urls": true,
"keyword_limit": 10,
"keyword_limit_enabled": true,
"url_limit": 10,
"url_limit_enabled": true
}
HTTP Request
POST https://api.nightwatch.io/api/v1/subusers?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
email* | Subuser email |
access_type* | Whether this is an "admin" or "limited" subuser |
adding_keywords | Whether this user can create new keywords |
adding_urls | Whether this user can create new URLs |
group_ids | URL groups' IDs this subuser has access to |
keyword_limit | Number of keywords this subuser can create |
keyword_limit_enabled | Whether keywords limit is enabled |
url_limit | Number of URLs this subuser can create |
url_limit_enabled | Whether URLs limit is enabled |
Parameters marked with * are mandatory.
Update a subuser
curl 'https://api.nightwatch.io/api/v1/subusers/SUBUSER_ID?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json' \\
-X PUT \\
-d '{
"subuser": {
"access_type": "limited",
"email": "[email protected]",
"group_ids": [100, 101, 102],
"adding_keywords": true,
"adding_urls": true,
"keyword_limit": 10,
"keyword_limit_enabled": true,
"url_limit": 10,
"url_limit_enabled": true,
"created": "less than a minute ago",
"last_access": null,
"last_login_ip": ""
}
}'
The above command returns JSON structured like this:
{
"access_type": "limited",
"group_ids": [100, 101, 102, 103],
"adding_keywords": true,
"adding_urls": true,
"keyword_limit": 20,
"keyword_limit_enabled": true,
"url_limit": 20,
"url_limit_enabled": true
}
HTTP Request
PUT https://api.nightwatch.io/api/v1/subusers/SUBUSER_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
subuser_id* | Subuser ID to be updated |
Parameters marked with * are mandatory.
Parameters
Parameter | Description |
---|---|
access_type | Whether this is an "admin" or "limited" subuser |
adding_keywords | Whether this user can create new keywords |
adding_urls | Whether this user can create new URLs |
group_ids | URL groups' IDs this subuser has access to |
keyword_limit | Number of keywords this subuser can create |
keyword_limit_enabled | Whether keywords limit is enabled |
url_limit | Number of URLs this subuser can create |
url_limit_enabled | Whether URLs limit is enabled |
Delete a subuser
curl 'https://api.nightwatch.io/api/v1/subusers/SUBUSER_ID?access_token=ACCESS_TOKEN' \\
-X DELETE \\
-H 'Content-Type: application/json' \\
The above command returns a HTTP 204 response.
HTTP Request
POST https://api.nightwatch.io/api/v1/subusers?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
subuser_id* | Subuser ID to be deleted |
Parameters marked with * are mandatory.
Groups
A group is a top-level container for your URLs and global keyword views.
List groups
curl 'https://api.nightwatch.io/api/v1/url_groups?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"id": 36242,
"name": "Example group",
"url_count": 0,
"url_type": null,
"group_type": "static",
"dynamic_view_count": 0
},
...
]
HTTP Request
GET https://api.nightwatch.io/api/v1/url_groups?access_token=ACCESS_TOKEN
Get a group
curl 'https://api.nightwatch.io/api/v1/url_groups/36242?access_token=ACCESS_TOKEN' \
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"id": 36242,
"name": "Renamed group",
"url_count": 0,
"url_type": null,
"group_type": "static",
"dynamic_view_count": 0
}
HTTP Request
GET https://api.nightwatch.io/api/v1/url_groups/GROUP_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
group_id | The id of the group |
Create a group
curl 'https://api.nightwatch.io/api/v1/url_groups?access_token=ACCESS_TOKEN' \\
-X POST \\
-H 'Content-Type: application/json' \\
-d '
{
"url_group": {
"name": "Example group",
}
}
'
The above command returns JSON structured like this:
{
"id": 36242,
"name": "Example group",
"url_count": 0,
"url_type": null,
"group_type": "static",
"dynamic_view_count": 0
}
HTTP Request
POST https://api.nightwatch.io/api/v1/url_groups?access_token=ACCESS_TOKEN
Body Parameters
Parameter | Description |
---|---|
name | The name of the group |
Update a group
curl 'https://api.nightwatch.io/api/v1/url_groups/36242?access_token=ACCESS_TOKEN' \\
-X PUT \\
-H 'Content-Type: application/json' \\
-d '
{
"url_group": {
"name": "Renamed group",
}
}
'
The above command returns JSON structured like this:
{
"id": 36242,
"name": "Renamed group",
"url_count": 0,
"url_type": null,
"group_type": "static",
"dynamic_view_count": 0
}
HTTP Request
PUT https://api.nightwatch.io/api/v1/url_groups/GROUP_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
group_id | The id of the group |
Body Parameters
Parameter | Description |
---|---|
name | The name of the group |
Delete a group
curl 'https://api.nightwatch.io/api/v1/url_groups/36242?access_token=ACCESS_TOKEN' \\
-X DELETE \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"id": 36242,
"name": "Example group",
"url_count": 0,
"url_type": null,
"group_type": "static",
"dynamic_view_count": 0
}
HTTP Request
DELETE https://api.nightwatch.io/api/v1/url_groups/GROUP_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
group_id | The id of the group |
URLs
URLs represent a site or domain for which a set of keywords are being tracked. URLs can also contain backlinks, and are used to perform site audits on. Althought these two last functionalities have their own endpoint, but their specific settings are configured with the URL endpoint.
URL data
Field | Description |
---|---|
id | URL ID |
url_type | URL engine type (deprecated) |
url | URL |
last_processed_at | Time when number of Google indexed pages was last retrieved |
created_at | Time when this URL was created |
keyword_count | Number of keywords this URL has |
domain_authority | Domain authority ranking |
domain_authority_change | Last observed change in domain authority |
google_indexed | Number of pages indexed by Google |
keyword_changes | How many keywords went up (1), went down (-1), or stayed the same (0) |
url_group_id | Group ID this URL belongs to |
places_info | Place extended matching data |
places_info.place_cid | Match place by CID |
places_info.place_title | Match place by title |
places_info.place_description | Places description, informational, no matching is performed on description |
url_info | Places_info alias |
places_match | Place's CID (cid_<CID> format) or, if CID is empty, place's title |
places_keyword | (deprecated) |
places_image_title | Title for tracking in image carousel |
custom_name | Custom URL name |
youtube_video_id | Youtube video ID, for Youtube video tracking purposes |
youtube_channel | Youtube channel name, for Youtube channel tracking purposes |
competitors | List of competitors this URL has |
google_indexed_change | Daily change of number of pages index by Google |
report_count | How many reports this URL has |
google_analytics_profile_id | Google Analytics profile ID, might be empty if GA integration is not setup |
country_code | ISO3166 alpha-2 country code |
language_code | ISO639 language code |
search_console_url | Google Search Console URL this URL matches with |
backlinks_enabled | Whether backlinks are enabled for this URL |
backlinks_status | Backlinks status data (read only) |
backlinks_count | Total number of backlinks |
google_analytics_updated_at | Last time GA data was updated |
backlinks_fetching_enabled | Whether this URL has recurring backlinks fetching enabled |
include_local_pack_in_main_position | Whether to include local pack rankings in the main one (boolean, default: true) |
include_places_image_in_main_position | Whether to include image carousel rankings in the main one (boolean, default: true) |
include_featured_snippet_in_main_position | Whether to include feature snippets rankings in the main one (boolean, default: true) |
include_knowledge_panel_in_main_position | Whether to include knowledge panel rankings in the main one (boolean, default: true) |
crawling_session_path_ignore_pattern | Ignore path patterns for site audits |
crawling_session_url_params_enabled | Whether to include query parameters in site audits (boolean, default: true) |
crawling_session_follow_nofollow_links | Whether to follow nofollow links in site audits (boolean, default: true) |
match_subdomains | Whether to match subdomains (boolean, default: false) |
match_nested_urls | Whether to match subpaths in the URL (boolean, default: true) |
site_audit_interval | Recurring site audit intervals (in seconds, accepted valud are: 604800 (1 week) and 2592000 (30 days)) |
backlinks_settings.ignored_domains | List of domain backlinks from will be ignored |
backlinks_settings.min_url_rating | Minimum URL rating for backlink domains |
next_site_audit_crawl_at | Next time a recurring site audit will happen (read only) |
site_audit_interval | Recurring site audit intervals (in seconds, accepted valud are: 604800 (1 week) and 2592000 (30 days)) |
backlinks_settings.ignored_domains | List of domain backlinks from will be ignored |
backlinks_settings.min_url_rating | Minimum URL rating for backlink domains |
seo_metrics | Moz, Majestic, and Ahref SEO metrics |
seo_metrics_changes | Last observed changes for Moz, Majestic, and Ahref SEO metrics |
match_subdomains | Whether to match URL subdomains |
match_nested_urls | Whether to match URL subpaths |
List URLs
curl 'https://api.nightwatch.io/api/v1/urls?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"id": 31234,
"url_type": "google",
"url_info": {},
"url": "http://example.com",
"last_processed_at": "2019-07-21T00:00:53.892Z",
"created_at": "2013-10-08T17:38:43.800Z",
"keyword_count": 17,
"domain_authority": 1,
"domain_authority_change": -1,
"google_indexed": 24,
"keyword_changes": {
"0": 16,
"1": 1,
"-1": 0
},
"url_group_id": 36241,
"places_info": null,
"places_match": null,
"places_keyword": null,
"places_image_title": null,
"custom_name": "",
...
},
...
]
HTTP Request
GET https://api.nightwatch.io/api/v1/urls?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
group_id | Only return URLs belonging to this group (optional) |
Get a URL
curl 'https://api.nightwatch.io/api/v1/urls/31234?access_token=ACCESS_TOKEN' \
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"id": 31234,
"url_type": "google",
"url_info": {},
"url": "http://example.com",
"last_processed_at": "2019-07-21T00:00:53.892Z",
"created_at": "2013-10-08T17:38:43.800Z",
"keyword_count": 17,
"domain_authority": 1,
"domain_authority_change": -1,
"google_indexed": 24,
"keyword_changes": {
"0": 16,
"1": 1,
"-1": 0
},
"url_group_id": 36241,
"places_info": null,
"places_match": null,
"places_keyword": null,
"places_image_title": null,
"custom_name": "",
...
}
HTTP Request
GET https://api.nightwatch.io/api/v1/urls/URL_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
url_id | The id of the URL to be fetched |
Create a URL
curl 'https://api.nightwatch.io/api/v1/urls?access_token=ACCESS_TOKEN' \\
-X POST \\
-H 'Content-Type: application/json' \\
-d '
{
"url": {
"url": "example.com",
"custom_name": "Example Site",
"country_code": "us",
"language_code": "en",
"places_match": null,
"match_nested_urls": false,
"match_subdomains": false,
"url_group_id": 1234,
}
}
'
The above command returns JSON structured like this:
{
"id": 31234,
"url_type": "google",
"url_info": {},
"url": "http://example.com",
"last_processed_at": "2019-07-21T00:00:53.892Z",
"created_at": "2013-10-08T17:38:43.800Z",
"keyword_count": 17,
"domain_authority": 1,
"domain_authority_change": -1,
"google_indexed": 24,
"keyword_changes": {
"0": 16,
"1": 1,
"-1": 0
},
"url_group_id": 36241,
"places_info": null,
"places_match": null,
"places_keyword": null,
"places_image_title": null,
"custom_name": "",
...
}
HTTP Request
POST https://api.nightwatch.io/api/v1/urls?access_token=ACCESS_TOKEN
Body Parameters
Parameter | Description |
---|---|
url* | URL to track |
custom_name | Custom URL name, used for displaying purposes |
country_code* | ISO3166 alpha-2 coutry code |
language_code* | ISO639-1 language code |
places_match | Place name or CID |
match_nested_urls | Whether to match subpaths in the URL |
match_subdomains | Whether to match subdomains |
url_group_id* | Group this URL will belong to |
Parameters marked with * are mandatory.
Note: country and language codes are used for retrieving the number of indexed pages by Google, and as a default setting for keywords. However, keywords have their own location and language specification, and are not affected by these settings.
Update a URL
curl 'https://api.nightwatch.io/api/v1/urls/31234?access_token=ACCESS_TOKEN' \\
-X PUT \\
-H 'Content-Type: application/json' \\
-d '
{
"url": {
"url": "www.example.com"
"custom_name": "Example URL"
"country_code": "si"
"language_code": "sl"
"places_match": "cid_123456789"
"match_nested_urls": true
"match_subdomains": false
"url_group_id": 12345
}
}
The above command returns JSON structured like this:
[
{
"id": 31234,
"url_type": "google",
"url_info": {},
"url": "http://example.com",
"last_processed_at": "2019-07-21T00:00:53.892Z",
"created_at": "2013-10-08T17:38:43.800Z",
"keyword_count": 17,
"domain_authority": 1,
"domain_authority_change": -1,
"google_indexed": 24,
"keyword_changes": {
"0": 16,
"1": 1,
"-1": 0
},
"url_group_id": 36241,
"places_info": null,
"places_match": null,
"places_keyword": null,
"places_image_title": null,
"custom_name": "",
...
}
]
HTTP Request
PUT https://api.nightwatch.io/api/v1/urls/URL_ID?access_token=ACCESS_TOKEN
Body Parameters
Parameter | Description |
---|---|
URL_ID | URL ID |
url_group_id | Group ID this URL belong to |
places_match | Place name or CID |
custom_name | Custom URL name, used for displaying purposes |
country_code | ISO3166 alpha-2 country code |
language_code | ISO639 language code |
include_local_pack_in_main_position | Whether to include local pack rankings in the main one (boolean, default: true) |
include_places_image_in_main_position | Whether to include image carousel rankings in the main one (boolean, default: true) |
include_featured_snippet_in_main_position | Whether to include feature snippets rankings in the main one (boolean, default: true) |
include_knowledge_panel_in_main_position | Whether to include knowledge panel rankings in the main one (boolean, default: true) |
crawling_session_path_ignore_pattern | Ignore path patterns for site audits |
crawling_session_url_params_enabled | Whether to include query parameters in site audits (boolean, default: true) |
crawling_session_follow_nofollow_links | Whether to follow nofollow links in site audits (boolean, default: true) |
match_subdomains | Whether to match subdomains (boolean, default: false) |
match_nested_urls | Whether to match subpaths in the URL (boolean, default: true) |
site_audit_interval | Recurring site audit intervals (in seconds, accepted valud are: 604800 (1 week) and 2592000 (30 days)) |
backlinks_settings.ignored_domains | List of domain backlinks from will be ignored |
backlinks_settings.min_url_rating | Minimum URL rating for backlink domains |
Delete a URL
curl 'https://api.nightwatch.io/api/v1/urls/31234?access_token=ACCESS_TOKEN' \\
-X DELETE \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"id": 31234,
"url_type": "google",
"url_info": {},
"url": "http://example.com",
"last_processed_at": "2019-07-21T00:00:53.892Z",
"created_at": "2013-10-08T17:38:43.800Z",
"keyword_count": 17,
"domain_authority": 1,
"domain_authority_change": -1,
"google_indexed": 24,
"keyword_changes": {
"0": 16,
"1": 1,
"-1": 0
},
"url_group_id": 36241,
"places_info": null,
"places_match": null,
"places_keyword": null,
"places_image_title": null,
"custom_name": "",
...
}
HTTP Request
DELETE https://api.nightwatch.io/api/v1/urls/URL_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
group_id | The id of the group |
Keywords
Keywords are queries or terms that are used to perform searches in search engines.
List keywords
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/keywords?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{ "id":1,
"last_processed_at":"2019-06-04T00:18:23.187Z",
"query":"goji berries",
"created_at":"2016-10-08T11:30:07.923Z",
"position":6,
"search_keyword_url_id":22199,
"mobile":false,
"local_search":null,
"google_hl":"sl",
"google_gl":"si",
"last_day_change":0,
"last_week_change":0,
"last_month_change":0,
"uri":"/",
"result_url":"https://topgojiberries.com/",
"last_position_change":[-1,"2019-05-26T00:18:40.646Z",true],
"results_count":2770,
"adwords_local_search_volume":0,
"adwords_local_average_cpc":0.0,
"adwords_global_search_volume":0,
"adwords_global_average_cpc":0.0,
"position_type":"organic",
"position_organic":6,
"position_places":null,
"position_places_image":null,
"position_local_pack":null,
"position_featured_snippet":null,
"position_knowledge_panel":null,
"tags":[{"id":"Branded","name":"Branded"},{"id":"Difficult","name":"Difficult"}],
"engine":"google",
"url":"http://topgojiberries.com",
"previous_position":5,
"best_position":1,
"position_changed_during_last_day":0,
"position_changed_during_last_week":0,
"position_changed_during_last_month":0,
"historic_positions":[6,6,6,6,6,6,6,6,6,6,5,5,5,5,8,8,8,8,8,8,8,8,8,7,8,7,7,6,6,6,6,5],
"last_historic_position_on":"2019-06-04",
"position_change":0,
"available_serp_features":{"places_image":false,"organic":true,"local_pack":false,"knowledge_panel":true,"featured_snippet":false}
}
]
HTTP Request
GET https://api.nightwatch.io/api/v1/urls/URL_ID/keywords?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
sort | The name of the field to sort by. Possible values: id, query, google_gl, google_hl, last_processed_at, created_at, updated_at, position, position_type, position_organic, position_places, position_places_image, position_changed_by, position_changed_status, position_changed_at, position_local_pack, position_featured_snippet, position_knowledge_panel, local_search, position_changed_during_last_day, position_changed_during_last_week, position_changed_during_last_month, mobile, engine, previous_position, best_position, available_serp_features, adwords_global_search_volume, adwords_global_average_cpc, adwords_local_search_volume, adwords_local_average_cpc |
direction | The direction to sort by. Possible values: asc, desc |
search | A general search string to filter by keywords' term, tags, result URL and location |
page | Page number (pagination) |
limit | Amount of keywords in a page |
Response headers
Header | Description |
---|---|
X-Page-Count | Number of pages for specified page limit |
X-Total-Count | Total number of keywords |
Add keywords
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/keywords/batch_create?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json' \\
-X POST \\
-d '{"keywords":"keyword1\nkeyword2\nkeyword3",
"tags":[],
"google_gl":"us",
"google_hl":"en",
"mobile":false,
"desktop":true,
"search_engine":
"google"
}'
The above command returns JSON structured like this:
[
{ "id":1,
"query":"keyword1",
...
}, {
"id":2,
"query":"keyword2",
...
},
...
]
HTTP Request
POST https://api.nightwatch.io/api/v1/urls/URL_ID/keywords?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
keywords* | Search queries separated by new lines (\n) |
google_hl* | Search language code (see here for available options) |
google_gl* | Search geolocation code (see here for available options) |
search_engine* | Search engine ('google', 'youtube', 'places', 'bing', 'yahoo' or 'duckduckgo') |
adwords_location_id | Search location Criteria ID (see here for available options) |
mobile | Search adjusted for mobile devices (true or false, default: false) |
desktop | Search adjusted for desktop devices (true or false, default: true) |
Parameters marked with * are mandatory.
Remove keywords
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/keywords/batch_destroy?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json' \\
-d '{"keyword_ids":["1","2"]}'
The above command returns a HTTP 204 response.
HTTP Request
POST https://api.nightwatch.io/api/v1/urls/URL_ID/keywords/batch_destroy?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
keyword_ids* | An array of keyword IDs for removal |
Parameters marked with * are mandatory.
Update a keyword
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/keywords/KEYWORD_ID?access_token=ACCESS_TOKEN' \\
-X PUT \\
-H 'Content-Type: application/json; charset=UTF-8' \\
-d '{"keyword":
{"tags":["Branded"]"}
}'
The above command returns a HTTP 204 response.
HTTP Request
PUT https://api.nightwatch.io/api/v1/urls/URL_ID/keywords/KEYWORD_ID?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
tags | An array of tags |
Keyword results
Every keyword gets a new result every day. A keyword result is a structure that contains data on the keyword's position for the specified URL in a SERP.
List results
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/keywords/KEYWORD_ID/results?time_start=2017-05-08&time_end=2017-05-09&access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"id": 24771,
"position": 42,
"result_url": "http://example.com",
"created_at": "2019-05-09 20:01:12 +0200",
"position_type": null,
"position_organic": null,
"position_places": null,
"position_places_image": null,
"position_local_pack": null,
"result_url_path": "/"
}
]
HTTP Request
GET https://api.nightwatch.io/api/v1/urls/URL_ID/keywords/KEYWORD_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
time_start* | The starting date in YYYY-MM-DD format (e.g. 2019-01-01) |
time_end* | The ending date in YYYY-MM-DD format (e.g. 2019-01-01) |
Competitors
Competitors are additional URLs that will be tracked along with the main URL. They are used to track competitor sites with the same set of keywords as the parent URL.
Competitor data
Field | Description |
---|---|
id | Competitor ID |
url | URL of the competitor |
search_keyword_url_id | URL ID this competitor belong to |
custom_name | Competitor custom name |
match_subdomains | Whether this competitor matches subdomains |
match_nested_urls | Whether this competitor matches nested URL paths |
places_image_title | Title for tracking in image carousel |
places_info | Place extended matching data |
places_info.place_cid | Match place by CID |
places_info.place_title | Match place by title |
places_info.place_description | Places description, informational, no matching is performed on description |
places_match | Place's CID (cid_<CID> format) or, if CID is empty, place's title |
List competitors
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/competitors?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"id":1,
"url": "http://example.com",
"match_nested_urls": true,
"match_subdomains": true,
"places_image_title": null,
"places_info": null,
"places_match": null,
"search_keyword_url_id": 10,
"custom_name": "Example Competitor"
},
...
]
HTTP Request
GET https://api.nightwatch.io/api/v1/urls/URL_ID/competitors?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
url_id | The id of the URL to fetch competitors for |
Add competitors
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/competitors?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json' \\
-X POST \\
-d '{
"competitor": {
"id": 2,
"url": "http://new.example.com/",
"match_subdomains": true,
"match_nested_urls": false,
"places_match": false,
"places_image_title": null,
"custom_name": "New Example Competitor"
}
}'
The above command returns JSON structured like this:
{
"id": 2,
"url": "http://new.example.com/",
"match_nested_urls": true,
"match_subdomains": true,
"places_image_title": null,
"places_info": null,
"places_match": null,
"search_keyword_url_id": 10,
"custom_name": "New Example Competitor"
}
HTTP Request
POST https://api.nightwatch.io/api/v1/urls/URL_ID/competitors?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
url* | URL to track |
match_subdomains | Whether to match subdomains |
match_nested_urls | Whether to match subpaths in the URL |
places_match | Place name or CID |
places_image_title | Title for tracking in image carousel |
custom_name | Custom competitor name |
Parameters marked with * are mandatory.
Remove competitor
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/competitors/COMPETITOR_ID?access_token=ACCESS_TOKEN' \\
-X DELETE \\
-H 'Content-Type: application/json' \\
The above command returns a HTTP 204 response.
HTTP Request
POST https://api.nightwatch.io/api/v1/urls/URL_ID/competitors/COMPETITOR_ID?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
url_id* | URL ID the competitor belongs to |
competitor_id* | Competitor ID to be deleted |
Parameters marked with * are mandatory.
Data Series
Using Nightwatch API, you can retrieve data series for the following resources:
- URL and Competitor URLs
- Keyword
- Keyword View
- Group
- Backlinks
- Backlink Views
All series are represented by an array of date-value pairs, which you can use to visualize graphs and calculate statistics.
URL Series
curl 'https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN&url_ids%5B%5D=161490&date_from=2019-04-02&date_to=2019-07-01&with_competitors=false'
The above command returns JSON structured like this:
[{
url_id: 161490,
url: "example.com",
url_series: [
{
name: "average_position",
series: [["2019-04-22", 100], ...]
}, ...
],
competitor_series: [
{
competitor_id: 123,
competitor_url: "example.com",
name: "average_position",
series: [["2019-04-22", 3], ...]
}, ...
]
]
HTTP Request
GET https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN
Parameter | Description |
---|---|
url_ids* | Array of URL ids |
with_competitors | Include competititor URL series (true or false, default: true) |
date_from* | Start date for series in YYYY-MM-DD format (e.g 2019-01-02) |
date_to* | End date for series in YYYY-MM-DD format (e.g. 2019-04-02) |
Parameters marked with * are mandatory.
Available URL series:
Series | Description |
---|---|
average_position | Average rank position |
search_visibility_index | Search visibility index (more info) |
click_potential | Click potential (more info) |
keyword_distribution | Distribution of keyword positions in Top 3, Top 10, Top 100, No rank |
total_keywords | Number of keywords tracked |
indexed_pages | Number of indexed pages on Google |
moz_domain_authority | Moz's Domain Authority |
moz_page_authority | Moz's Page Authority |
ahrefs_domain_rating | Ahrefs' Domain Rating |
ahrefs_rank | Ahrefs' URL Rank |
majestic_trust_flow | Majestic's Trust Flow |
majestic_citation_flow | Â Majestic's Citation Flow |
clicks | Â Number of organic search clicks (when Search Console property is connected) |
impressions | Â Number of organic search impressions (when Search Console property is connected) |
sessions | Â Number of Google Analytics Sessions (when Google Analytics property is connected) |
pageviews | Â Number of Google Analytics Pageviews (when Google Analytics property is connected) |
users | Â Number of Google Analytics Users (when Google Analytics property is connected) |
search_console_position | Â Search Console average position (when Search Console property is connected) |
ctr | Â Search Console CTR (when Search Console property is connected) |
Keyword series
curl 'https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN&keyword_ids%5B%5D=1212189&date_from=2019-06-04&date_to=2019-07-04'
The above command returns JSON structured like this:
[{
keyword_id: 1212189,
keyword: "goji berries",
keyword_series: [
{
name: "position",
series: [["2019-04-22", 3], ...]
}, ...
],
competitor_series: [
{
competitor_id: 123,
competitor_url: "example.com",
name: "position",
series: [["2019-04-22", 3], ...]
}, ...
]
]
HTTP Request
GET https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN
Parameter | Description |
---|---|
keyword_ids* | Array of keyword ids |
date_from* | Start date for series in YYYY-MM-DD format (e.g 2019-01-02) |
date_to* | End date for series in YYYY-MM-DD format (e.g. 2019-04-02) |
Parameters marked with * are mandatory.
Available keyword series:
Series | Description |
---|---|
position | Keyword's rank |
position_organic | Keyword's organic rank |
position_local_pack | Keyword's local pack rank |
position_places | Keywords rank in Google Places (when engine is Google Places) |
position_places_image | Keywords rank in image carousel (when engine is Google) |
clicks | Â Number of organic search clicks (when Search Console property is connected) |
impressions | Â Number of organic search impressions (when Search Console property is connected) |
search_console_position | Â Search Console average position (when Search Console property is connected) |
ctr | Â Search Console CTR (when Search Console property is connected) |
Keyword view series
curl 'https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN&dynamic_view_ids%5B%5D=123&date_from=2019-06-04&date_to=2019-07-04'
[{
dynamic_view_id: 161490,
dynamic_view_name: "A view"
dynamic_view_series: [
{
name: "average_position",
series: [["2019-06-04", 10], ...]
}, ...
]
]
HTTP Request
GET https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN
Parameter | Description |
---|---|
dynamic_view_ids* | Array of keyword view ids |
date_from* | Start date for series in YYYY-MM-DD format (e.g 2019-01-02) |
date_to* | End date for series in YYYY-MM-DD format (e.g. 2019-04-02) |
Parameters marked with * are mandatory.
Available keyword series:
Series | Description |
---|---|
average_position | Average rank position |
search_visibility_index | Search visibility index (more info) |
click_potential | Click potential (more info) |
keyword_distribution | Distribution of keyword positions in Top 3, Top 10, Top 100, No rank |
total_keywords | Number of keywords that fall into view's filters on specified days |
up_down | Number of keywords whose position increased and decreased |
Group series
curl 'https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN&url_group_ids%5B%5D=123&date_from=2019-06-04&date_to=2019-07-04'
[{
url_group_id: 123,
url_group_name: "A group"
url_group_series: [
{
name: "average_position",
series: [["2019-06-04", 10], ...]
}, ...
]
]
HTTP Request
GET https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN
Parameter | Description |
---|---|
url_group_ids* | Array of group ids |
date_from* | Start date for series in YYYY-MM-DD format (e.g 2019-01-02) |
date_to* | End date for series in YYYY-MM-DD format (e.g. 2019-04-02) |
Parameters marked with * are mandatory.
Available keyword series:
Series | Description |
---|---|
average_position | Average rank position |
search_visibility_index | Search visibility index (more info) |
click_potential | Click potential (more info) |
keyword_distribution | Distribution of keyword positions in Top 3, Top 10, Top 100, No rank |
total_keywords | Number of keywords in the group on specified days |
up_down | Number of keywords whose position increased and decreased |
Backlink series (for a URL)
curl 'https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN&url_id_for_all_backlinks=123&date_from=2019-06-04&date_to=2019-07-04'
[{
backlink_view_series: [
{
name: "backlinks_total",
series: [["2019-06-04", 10], ...]
},
{
name: "backlinks_referring_ips",
series: [["2019-06-04", 10], ...]
}, ...
]
]
HTTP Request
GET https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN
Parameter | Description |
---|---|
url_id_for_all_backlinks* | URL id |
date_from* | Start date for series in YYYY-MM-DD format (e.g 2019-01-02) |
date_to* | End date for series in YYYY-MM-DD format (e.g. 2019-04-02) |
Parameters marked with * are mandatory.
Available backlink series:
Series | Description |
---|---|
backlinks_all | Active backlinks |
backlinks_total | Total backlinks |
backlinks_referring_ips | Referring IPs |
backlinks_referring_domains | Referring Domains |
backlinks_referring_subnets | Referring Subnets |
Backlink series (for a view)
curl 'https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN&backlink_view_ids%5B%5D=123&date_from=2019-04-02&date_to=2019-07-01'
[{
backlink_view_id: 123,
backlink_view_name: "DR > 10"
backlink_view_series: [
{
name: "backlinks_total",
series: [["2019-06-04", 10], ...]
},
{
name: "backlinks_referring_ips",
series: [["2019-06-04", 10], ...]
}, ...
]
]
HTTP Request
GET https://api.nightwatch.io/api/v1/series?access_token=ACCESS_TOKEN
Parameter | Description |
---|---|
backlink_view_ids* | Backlink view ids |
date_from* | Start date for series in YYYY-MM-DD format (e.g 2019-01-02) |
date_to* | End date for series in YYYY-MM-DD format (e.g. 2019-04-02) |
Parameters marked with * are mandatory.
Available backlink series:
Series | Description |
---|---|
backlinks_all | Active backlinks |
backlinks_total | Total backlinks |
backlinks_referring_ips | Referring IPs |
backlinks_referring_domains | Referring Domains |
backlinks_referring_subnets | Referring Subnets |
Data Stats
Calculates statistics for a specified URL or View in a given date range.
Keyword Stats
curl 'https://api.nightwatch.io/api/v1/keyword_stats?access_token=ACCESS_TOKEN&start_date=07-03-2019&end_date=08-02-2019&dynamic_view_id=5106&url_id=80337' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"average_position": 39.0,
"average_position_change": -24.3,
"search_visibility_index": 3.7,
"search_visibility_index_change": -76.7,
"click_potential": 163.2,
"click_potential_change": -412.0,
"top3_count": 0,
"top3_change": -2,
"top10_count": 0,
"top10_change": 0,
"top100_count": 2,
"top100_change": 1,
"no_rank_count": 0,
"no_rank_change": 0,
"keywords_went_up": 0,
"keywords_went_down": 2,
"keywords_unchanged": 0,
"keyword_count": 4,
"url_count": 1,
"average_positions": [
["2019-07-03", 14.67],
["2019-07-04", 8.0],
...
],
"search_visibility_series": [
["2019-07-03", 80.4],
["2019-07-04", 8.17],
...
],
"click_potential_series": [
["2019-07-03", 575.16],
["2019-07-04", 348.37],
...
],
"keyword_distribution_series": [
[
"2019-07-03",
{
"top_3": 2.0,
"top_10": 0.0,
"top_100": 1.0,
"no_rank": 0.0
}
],
[
"2019-07-04",
{
"top_3": 0.0,
"top_10": 1.0,
"top_100": 0.0,
"no_rank": 0.0
}
],
...
],
"keyword_up_down_series": [
[
"2019-07-03",
{
"went_up": 3.0,
"went_down": 0.0,
"stagnant": 0.0
}
],
[
"2019-07-04",
{
"went_up": 1.0,
"went_down": 0.0,
"stagnant": 0.0
}
],
...
],
"indexed_pages": 289,
"indexed_pages_change": -117,
"indexed_pages_series": [
["2019-07-03", 406],
["2019-07-04", 317],
...
]
}
HTTP Request
GET https://api.nightwatch.io/api/v1/keyword_stats?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
start_date* | The starting date in YYYY-MM-DD format (e.g. 2019-01-01) |
end_date* | The ending date in YYYY-MM-DD format (e.g. 2019-01-31) |
url_id | The URL id to calculate stats for |
dynamic_view_id | The dynamic view id to calculate stats for |
It's mandatory to specify either an url_id
or dynamic_view_id
.
Available stats:
Stat | Description |
---|---|
average_position | Latest average rank |
average_position_change | Average rank change |
search_visibility_index | Latest search visibility index (more info) |
search_visibility_index_change | Search visibility index change |
click_potential | Latest click potential (more info) |
click_potential_change | Click potential change |
top3_count | Latest distribution of keywords in top 3 ranks |
top3_change | Change in distribution of keywords in top 3 ranks |
top10_count | Latest distribution of keywords in top 10 ranks |
top10_change | Change in distribution of keywords in top 10 ranks |
top100_count | Latest distribution of keywords in top 100 ranks |
top100_change | Change in distribution of keywords in top 100 ranks |
no_rank_count | Latest distribution of keywords not ranking |
no_rank_change | Change in distribution of keywords not ranking |
keywords_went_up | Number of keywords that went up |
keywords_went_down | Number of keywords that went down |
keywords_unchanged | Number of keywords that remained unchanged |
keyword_count | Total number of keywords |
url_count | Total number of URLs |
average_positions | Average position time series |
search_visibility_series | Search visibility time series |
click_potential_series | Click potential time series |
keyword_distribution_series | Keyword distribution time series |
keyword_up_down_series | Keywords up/down time series |
indexed_pages | Latest number of pages indexed by Google |
indexed_pages_change | The change of number of pages indexed by Google |
indexed_pages_series | The number of pages indexed by Google time series |
Keyword Views
Keyword views are segmented keyword lists defined by a set of filters. They can match keywords across the whole account (global views) or they can be scoped to a single URL (URL views).
Available filters and conditions
Filter | Data type | Description |
---|---|---|
query | string | Keyword term |
position_changed_at | date | Time of last position change |
location | string | Keyword's location |
language | string | Keyword's name |
position | number | Keyword's position |
position_organic | number | Keyword's organic position |
position_local_pack | number | Keyword's local pack position |
position_featured_snippet | number | Keyword's featured snippet position |
position_knowledge_panel | number | Keyword's knowledge panel position |
search_volume_global | number | Keyword's global SV |
search_volume_local | number | Keyword's local SV |
average_cpc_global | number | Keyword's global CPC |
average_cpc_local | number | Keyword's local CPC |
day_change | number | Position change in the last day |
week_change | number | Position change in the last week |
month_change | number | Position change in the last month |
keyword_created_at | date | Keyword's creation date |
keyword_tag | string | Keyword's tag |
engine | string | Engine (possible values: google, bing, yahoo, duckduckgo, youtube, places) |
mobile | boolean | Whether the keyword is mobile (possible values: true, false) |
keyword_last_processed_at | date | Time of last position refresh |
result_url | string | Keyword's ranking URL in SERP |
String data type conditions
Condition |
---|
contains |
starts_with |
ends_with |
equals |
not_contains |
not_starts_with |
not_ends_with |
not_equals |
Number and date data type conditions
Condition |
---|
less |
more |
less_or_equal |
more_or_equal |
equals |
Presence and absence conditions
Condition |
---|
present |
absent |
These conditions only apply to the following fields: position_organic, position_local_pack, position_places_image, position_featured_snippet, position_knowledge_panel, search_volume_global, search_volume_local, average_cpc_global, average_cpc_local, result_url.
Forming filters
Using the provided filters and conditions, you can freely form a filter block using the following form:
// A filter block to search for keywords with global SV larger than 200
{
field:"search_volume_global",
condition:"more",
value:2000
}
// A filter block to search for keywords that have a position (they are ranking)
{
field:"position",
condition:"present"
}
// A filter block to search for keywords with a specific tag:
{
field:"keyword_tag",
condition:"equals",
value:"Branded"
}
Combining filters
To prepare filter blocks to be used in a query, they need to be put in filter groups
.
A filter group is a group of filters tied together with OR
logical operator.
Multiple filter groups are tied together with AND
logical operator.
filter groups
are used for advanced keyword filtering and saving views (described in the next sections).
// Joining filters into a group.
// OR example:
// This example reads as: "return keywords with position 1 together with keywords with position more than 50"
filter_groups = [{
filters: [
{
field:"position",
condition:"equals",
value:"1"
},
{
field:"position",
condition:"more",
value:"50"
}
]
}]
// AND example:
// This example reads as: "return keywords with position 1 that have search volume larger than 10000"
filter_groups = [{
filters: [
{
field:"position",
condition:"equals",
value:"1"
}
]
}, {
filters: [
{
field:"search_volume_local",
condition:"more",
value:10000
}
]
}]
Keyword filtering
While views are intended for saving a particular filter set and then being used as saved keyword segments, it's also possible to use them to filter keywords on the fly.
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/keywords?access_token=ACCESS_TOKEN \
filter_groups=[{"filters":[{"field":"position","condition":"equals","value":"1"}]}]
The above command returns JSON structured like this:
[
{ "id":1,
"last_processed_at":"2019-06-04T00:18:23.187Z",
"query":"goji berries",
"created_at":"2016-10-08T11:30:07.923Z",
"position":6,
"search_keyword_url_id":22199,
...
}
]
HTTP Request
GET https://api.nightwatch.io/api/v1/urls/URL_ID/keywords
URL Parameters
Parameter | Description |
---|---|
filter_groups | Filter configuration |
direction | The direction to sort by. Possible values: asc, desc |
search | A general search string to filter by keywords' term, tags, result URL and location |
page | Page number (pagination) |
group_id | Group ID |
scope | When group ID is not provided, this value has to be "account" |
limit | Amount of keywords in a page |
curl 'https://api.nightwatch.io/api/v1/dynamic_views?access_token=ACCESS_TOKEN&group_id=123
The above command returns JSON structured like this:
[
{
"id":5878,
"name":"Branded",
"search_keyword_url_id":22199,
"url_group_id":null,
"keyword_count":4,
"report_count":0
},
...
]
HTTP Request
GET https://api.nightwatch.io/api/v1/dynamic_views?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
group_id | Views belonging to a specific group |
search_keyword_url_id | Views belonging to a specific url |
- at least one of the group_id or search_keyword_url_id parameters must be present
Create a view
A view is set up in two phases. First we create the view, and then we create the filters.
curl 'https://api.nightwatch.io/api/v1/dynamic_views?access_token=access_token \
-H 'Accept: application/json' \
-X POST \
-d '{"dynamic_view":{"name":"Example view","url_group_id":"26738"}}'
The above command returns JSON structured like this:
{
"id":58375,
"name":"Example view",
"search_keyword_url_id":null,
"url_group_id":26738,
"keyword_count":397,
"report_count":0
}
HTTP Request
POST https://api.nightwatch.io/api/v1/dynamic_views
URL Parameters
Parameter | Description |
---|---|
name | View's name |
group_id | View belonging to a specific group |
search_keyword_url_id | View belonging to a specific url |
- at least one of the group_id or search_keyword_url_id parameters must be present
Next, after a view has been created, we need to create create its filter groups:
curl 'https://api.nightwatch.io/api/v1/dynamic_views/VIEW_ID/filter_groups?access_token=ACCESS_TOKEN \
-H 'Content-Type: application/json' \
-X POST \
-d '{"filter_group":{"filters":[{"field":"query","condition":"contains","value":"example"}]}}'
The above command returns JSON structured like this:
{"id":60091,
"dynamic_view_id":58375,
"filters":[{"id":64359,"field":"query","condition":"contains","value":"example"
}
HTTP Request
POST https://api.nightwatch.io/api/v1/dynamic_views/VIEW_ID/filter_groups
URL Parameters
Parameter | Description |
---|---|
filters | Array of filter groups |
- If you have multiple filter groups (AND filters chaining), you have to make multiple
filter_groups
POST
requests.
List views
curl 'https://api.nightwatch.io/api/v1/dynamic_views?url_id=123&access_token=ACCESS_TOKEN
The above command returns JSON structured like this:
[
{
"id":58375,
"name":"Example view",
"url_group_id":26738,
"keyword_count":397,
"report_count":0
}
]
HTTP Request
GET https://api.nightwatch.io/api/v1/dynamic_views
URL Parameters
Parameter | Description |
---|---|
url_id | Filter by URL ID (get views belonging to specified URL) |
group_id | Filter by GROUP ID (get views belonging to specified group) |
without_counts | When true, there is no keyword_count and report_count in the response (makes querying faster) |
Get a view
curl 'https://api.nightwatch.io/api/v1/dynamic_views/VIEW_ID?access_token=ACCESS_TOKEN
The above command returns JSON structured like this:
{
"id":58375,
"name":"Example view",
"search_keyword_url_id":null,
"url_group_id":26738,
"keyword_count":397,
"report_count":0
}
HTTP Request
GET https://api.nightwatch.io/api/v1/dynamic_views/VIEW_ID
Get view's filtered keywords
Once the view is persisted and its filters configured, we can use it to get its filtered keywords.
curl 'https://api.nightwatch.io/api/v1/urls/URL_ID/keywords?access_token=ACCESS_TOKEN&dynamic_view_id=VIEW_ID'
HTTP Request
GET https://api.nightwatch.io/api/v1/urls/URL_ID/keywords
URL Parameters
Parameter | Description |
---|---|
dynamic_view_id* | View's ID |
sort | The name of the field to sort by. Possible values: id, query, google_gl, google_hl, last_processed_at, created_at, updated_at, position, position_type, position_organic, position_places, position_places_image, position_changed_by, position_changed_status, position_changed_at, position_local_pack, position_featured_snippet, position_knowledge_panel, local_search, position_changed_during_last_day, position_changed_during_last_week, position_changed_during_last_month, mobile, engine, previous_position, best_position, available_serp_features, adwords_global_search_volume, adwords_global_average_cpc, adwords_local_search_volume, adwords_local_average_cpc |
direction | The direction to sort by. Possible values: asc, desc |
page | Page number (pagination) |
scope | When group ID is not provided, this value has to be "account" |
limit | Amount of keywords in a page |
Parameters marked with * are mandatory.
Update a view
You can update the view's name.
curl 'https://api.nightwatch.io/api/v1/dynamic_views/59203?access_token=ACCESS_TOKEN' \\
-X PUT \\
-H 'Content-Type: application/json; charset=UTF-8' \\
--data-binary '{"dynamic_view":{"name":"Top 3 keywords"}}'
HTTP Request
GET https://api.nightwatch.io/api/v1/dynamic_views/VIEW_ID
URL Parameters
Parameter | Description |
---|---|
name* | View's name |
Parameters marked with * are mandatory.
The above command returns JSON structured like this:
{
"id":58375,
"name":"Example view",
"search_keyword_url_id":null,
"url_group_id":26738,
"keyword_count":397,
"report_count":0
}
Delete a view
curl 'https://api.nightwatch.io/api/v1/dynamic_views/59203?access_token=ACCESS_TOKEN \
-X DELETE
The above command returns JSON structured like this:
{
"id":58375,
"name":"Example view",
"search_keyword_url_id":null,
"url_group_id":26738,
"keyword_count":397,
"report_count":0
}
HTTP Request
DELETE https://api.nightwatch.io/api/v1/dynamic_views/VIEW_ID
The above command returns JSON structured like this:
{
"id":58375,
"name":"Example view",
"search_keyword_url_id":null,
"url_group_id":26738,
"keyword_count":397,
"report_count":0
}
SERPs
This section describes getting SERP data for a specified keyword result.
Get SERP Data
curl 'https://api.nightwatch.io/api/v1/serp_data/RESULT_ID?access_token=ACCESS_TOKEN'
The above command returns JSON structured like this:
{
"keyword":"example",
"engine":"google",
"rank_time":"2019-08-25T03:11:51.614409Z",
"rank_date":"2019-08-25",
"locale":"en",
"data_center":"us",
"location":"New York, New York, United States",
"total_number_of_results":160000,
"serp":{
"1":{
"title":"Example #1",
"href":"https://test.example.com/page/1",
"description":"This is the first example",
"base_url":"test.example.com",
"base_domain":"example.com",
"position":1
},
"2":{
"title":"Example #2",
"href":"https://www.example.com/2",
"description":"This is the second example",
"base_url":"www.example.com",
"base_domain":"example.com",
"position":2
},
// ...
// result slots can be null if they're
// missing (e.g. less than 100 results)
"100":null
},
"local_pack":{
"results":[
{
"title":"Local result",
"cid": "1234567890",
"href":"https://www.example.com/local"
}
],
"present":true
},
"local_image_carousel":{
"results":[
{
"title":"Local result"
}
],
"present":true
},
"knowledge_panel":{
"results":[
{
"title":"Knowledge panel result",
"cid": "1234567890",
"href":"https://www.example.com/knowledge-panel"
}
],
"present":true
},
"featured_snippets":{
"results":[
{
"title":"Featured snippet result",
"href":"https://www.example.com/snippet"
}
],
"present":true
}
}
HTTP Request
GET https://api.nightwatch.io/api/v1/serp_data/RESULT_ID?access_token=ACCESS_TOKEN
Response structure:
Attribute | Description |
---|---|
keyword | Keyword query string |
engine | Search engine (google, places, bing, yahoo, duckduckgo, youtube) |
rank_time | The time the SERP was processed |
rank_date | The date the SERP was processed |
locale | Requested search language (e.g. en) |
data_center | Requested search country (e.g. us) |
location | Search location (e.g. New York, New York, United States) |
total_number_of_results | The total number of search results |
serp | A JSON object of ranked organic results |
local_pack | A JSON object containing a list of local pack results |
local_image_carousel | A JSON object containing a list of carousel results |
knowledge_panel | A JSON object containing a list of knowledge panel results |
featured_snippets | A JSON object containing a list of featured snippet results |
Search API
The Search API is a feature in Nightwatch where you submit a search engine query to Nightwatch, then Nightwatch performs a search engine query, gets the SERP, extracts data and enables you to download it.
This feature is useful for scraping Google via Nightwatch's system and getting SERP data for specified queries.
The Search API is used to perform on demand search requests using your allocated account credits. Credits can be bought via an external form. Please contact support if you want to buy more. To check how many credits you have, check the user endpoint.
Every search request costs a certain amount of credits, depending on the request type. You can learn more about it in our docs - check the section under "Partner API" (this is a legacy name for Search API).
The searches are always performed asynchronously, and you can subscribe to them using the callback url that you've provided to our support team.
Alternatively you can also poll a serach request until it is processed and the done
flag is set to true
.
You can also query search requests using the custom_id
in place of the serach request id.
List search requests
Return a list of the 100 most recent search requests.
curl 'https://api.nightwatch.io/api/v1/partner/search_requests?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"id": 1,
"engine": "google",
"query": "coffee shop",
"done": true,
"processed_at": "2019-08-27T20:02:00.000+02:00",
"created_at": "2019-08-27T20:01:00.000+02:00",
"results_url": "https://example.com/results/search_request_1.json"
"google_gl": "us",
"google_hl": "en",
"error": false,
"location_text": null,
"location_criteria_id": null,
"instant": true,
"accuracy": "normal",
"custom_id": null,
"mobile": false
}
]
HTTP Request
GET https://api.nightwatch.io/api/v1/partner/search_requests?access_token=ACCESS_TOKEN
Show search request
curl 'https://api.nightwatch.io/api/v1/partner/search_requests/REQUEST_ID?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"id": 1,
"engine": "google",
"query": "coffee shop",
"done": true,
"processed_at": "2019-08-27T20:02:00.000+02:00",
"created_at": "2019-08-27T20:01:00.000+02:00",
"results_url": "https://example.com/results/search_request_1.json"
"google_gl": "us",
"google_hl": "en",
"error": false,
"location_text": null,
"location_criteria_id": null,
"instant": true,
"accuracy": "normal",
"custom_id": null,
"mobile": false
}
HTTP Request
GET https://api.nightwatch.io/api/v1/partner/search_requests/REQUEST_ID?access_token=ACCESS_TOKEN
URL Parameters
Parameter | Description |
---|---|
custom_id | Set to true if you would like to query the search request by custom_id instead |
Make a search request
curl 'https://api.nightwatch.io/api/v1/partner/search_requests?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json' \\
-X POST \\
-d '{
"engine": "google",
"query": "coffee shop",
"google_hl": "en",
"google_gl": "us",
"location_criteria_id": 1014221,
"instant": true,
"mobile": false,
"accuracy": "normal"
}'
The above command returns JSON structured like this:
{
"id": 1,
"engine": "google",
"query": "coffee shop",
"done": false, // true once processed
"processed_at": null, // set once processed
"created_at": "2019-08-27T20:02:00.000+02:00",
"results_url": null, // url to the SERP JSON once processed
"google_gl": "us",
"google_hl": "en",
"error": false,
"location_text": null,
"location_criteria_id": null,
"instant": true,
"accuracy": "normal",
"custom_id": null,
"mobile": false
}
When the search request is performed, you will receive the SERP JSON on your configured callback URL like this:
{
"_id": 1, // search request id
"keyword":"coffee shop",
"engine":"google",
"rank_time":"2019-08-25T03:11:51.614409Z",
"rank_date":"2019-08-25",
"locale":"en",
"data_center":"us",
"location":nil,
"total_number_of_results":160000,
"serp":{ ... },
"local_pack":{ ... },
"local_image_carousel":{ ... },
"knowledge_panel":{ ... },
"featured_snippets":{ ... },
}
HTTP Request
POST https://api.nightwatch.io/api/v1/partner/search_requests?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
engine* | Search engine (google, places, bing, yahoo, duckduckgo, youtube) |
query* | Keyword query string |
google_hl | Language (e.g. en) |
google_gl | Location (e.g. us) |
location_criteria_id | Search location Criteria ID (see https://developers.google.com/ad-exchange/rtb/geotargeting) - Google only |
custom_id | Custom ID used in your system |
mobile | Mobile search (true/false) - Google only |
instant* | Instant processing - true (process as soon as possible) / false (process when available) |
accuracy* | Accuracy - normal (100 results per page) / high (10 results per page concatenated) |
Parameters marked with * are mandatory.
Make search requests (batch)
You can create multiple search requests in batches of max 100.
curl 'https://api.nightwatch.io/api/v1/partner/search_requests?access_token=ACCESS_TOKEN' \\
-H 'Content-Type: application/json' \\
-X POST \\
-d '{
"batch": [
{
"engine": "google",
"query": "coffee shop",
"google_hl": "en",
"google_gl": "us",
"location_criteria_id": 1014221,
"instant": true,
"mobile": false,
"accuracy": "normal"
},
{
"engine": "google",
"query": "diner",
"google_hl": "en",
"google_gl": "us",
"location_criteria_id": 1014221,
"instant": true,
"mobile": false,
"accuracy": "normal"
},
]
}'
The above command returns JSON structured like this:
[
{
"id": 1,
"engine": "google",
"query": "coffee shop",
"done": false, // true once processed
"processed_at": null, // set once processed
"created_at": "2019-08-27T20:02:00.000+02:00",
"results_url": null, // url to the SERP JSON once processed
"google_gl": "us",
"google_hl": "en",
"error": false,
"location_text": null,
"location_criteria_id": null,
"instant": true,
"accuracy": "normal",
"custom_id": null,
"mobile": false
},
{
"id": 1,
"engine": "google",
"query": "diner",
"done": false, // true once processed
"processed_at": null, // set once processed
"created_at": "2019-08-27T20:02:00.000+02:00",
"results_url": null, // url to the SERP JSON once processed
"google_gl": "us",
"google_hl": "en",
"error": false,
"location_text": null,
"location_criteria_id": null,
"instant": true,
"accuracy": "normal",
"custom_id": null,
"mobile": false
}
// ...
]
HTTP Request
POST https://api.nightwatch.io/api/v1/partner/search_requests?access_token=ACCESS_TOKEN
Parameters
Parameter | Description |
---|---|
batch* | A list of search requests to perform (max 100). See search request params. |
Parameters marked with * are mandatory.