NAV Navbar
shell

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:

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
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
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

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

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

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.