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
email	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
email	Email
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
email	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.

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.