Process SERP

This endpoint searches Google, processes the top 20 search results (SERP), and aggregates insights for those pages. You can optionally include a URL you want Frase to topic score against the SERP.



This is a  POST request.

You must include your API key as a "token" field in your request header.

There are 2 ways to process search results, which follow different payloads:

  1. Using Google Search API to get results
  2. Sending your own list of URLs

1. Using Google Search API to get results

Frase will perform a Google Search and process search results.

Argument Description
query The search query. string
lang Language for search results. string (default: "en")
country Country for search results. string (default: "us")
count Number of search results. integer (default: 20)
include_full_text Whether you want the response to include full text for each URL. boolean (default: false)
user_url The URL you want to run topic scoring against. string (optional field)
google_api_key Your Google API Key. Required for high volume usage. You can find in your Google Console dashboard.
google_search_engine_id Your Google Search Engine Id. Required for high volume usage. How to create a Google search engine.

Request Body Example:

  "query" : "what is an AI chatbot?",
  "lang" : "en",
  "country" : "us",
  "count" : 20,
  "include_full_text" : false,
  "user_url" : ""

2. Sending your own list of URLs

If you already have a list of URLs with you, then you don't need to have Frase search Google.

In this case, you can simplify your payload and directly send the list of URLs as "serp_urls". 

Argument Description
serp_urls The list of URLs you want to process. Send as list of strings
user_url The URL you want to run topic scoring against. string (optional field)

Request Body Example:

   "serp_urls" : [


If successful, the response will include the following fields:

Field Description
items List of processed URLs. See below detailed information about the Items object.
cluster_info List of topic clusters, where each cluster has "cluster_entities" and "label"
aggregate_metrics Average word count, average headers, and average external links per item. This will also include avg. topic score if "user_url" was part of the payload.
user_url_metrics Topic score, word count, header count, and external link count for the "user_url". This field is only returned if "user_url" was part of the payload.

The Items Object

The Items object includes a list, with one object per processed URL. 

Each processed URL includes the following data:

Field Description
title title tag
url canonical URL
description description tag
date date published tag
author author tag
links list of hyperlinks
images list of image URLs
language language tag
clean_text full clean text
html clean html for content
word_count clean text word count
assets list of sections with headings and text
questions list of question headings
entities list of topics sorted by count
statistics list of sentences containing stats