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.

Endpoint:

https://api.frase.io/api/v1/process_serp

Request:

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:

Using Google Search API to get results
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" : "https://www.theatlantic.com/technology/archive/2022/06/google-engineer-sentient-ai-chatbot/661273/"
}

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" : [
     "https://www.goodhousekeeping.com/home/gardening/g4348/summer-flowers/",
     "https://www.countryliving.com/life/g32036880/flowers-bloom-in-summer/",
     "https://www.gardendesign.com/flowers/easy.html",
     "https://www.familyhandyman.com/list/best-northern-summer-color-plants/",
     "https://www.fnp.com/blog/summer-flowering-plants-for-pots"
   ]
}

Response:

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

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