Agentic Platform
Documentation API reference Tools Skills

Tools

Google Position-based Click Opportunities

google_position_opportunities

Analyze potential click gains from ranking position improvements.

Analyze potential click gains from improving search ranking positions for specific URLs or keywords. This agent uses historical Search Console data to calculate the expected additional clicks you could gain by improving from your current position to better positions, broken down by device type (mobile and desktop/tablet).

Playground

POST
item
period required

Time period to analyze

url

Specific URL to analyze (optional)

keyword

Specific keyword to analyze (optional)

Credits

Fixed cost per item requested, plus the data the query scans. Keyword and ranking history is read from your project, and a wider date range scans more of it.

These usage SKUs can be charged on a call.

SKU Credits Description
Tool call 1 per request Charged once per successful item, on top of any usage below.
Data scanned 6,250 per TiB scanned Analytical queries are billed on the volume of data the query reads, not on the rows it returns: a narrow filter over a large table can still scan the whole table.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Properties
period string required

Time period to analyze

Values: last_7d last_28d

url string | null

Specific URL to analyze (optional)

Default: null

keyword string | null

Specific keyword to analyze (optional)

Default: null

Example
{
  "period": "last_7d",
  "url": null,
  "keyword": null
}

Response

object
Properties
global_ctr_mobile array required

Global CTR data for mobile devices by position

Items: CTRDataPoint

global_ctr_desktop_and_tablet array required

Global CTR data for desktop and tablet devices by position

Items: CTRDataPoint

ctr_for_filter FilteredCTRMetrics required

CTR metrics for the specific URL or keyword filter

Items: FilteredCTRMetrics

opportunities OpportunitiesByDevice required

Potential additional clicks by improving to each position

Type: OpportunitiesByDevice

opportunities_explanations string required

Explanation of what the opportunities data represents

Example
{
  "global_ctr_mobile": [
    {
      "avg_position": 0,
      "device": "string",
      "nb_urls": 0,
      "pct_urls_with_clicks": 0.0,
      "impressions": 0,
      "clicks": 0,
      "ctr_global": 0.0
    }
  ],
  "global_ctr_desktop_and_tablet": [
    {
      "avg_position": 0,
      "device": "string",
      "nb_urls": 0,
      "pct_urls_with_clicks": 0.0,
      "impressions": 0,
      "clicks": 0,
      "ctr_global": 0.0
    }
  ],
  "ctr_for_filter": [
    {
      "impressions": 0,
      "clicks": 0,
      "ctr": 0.0,
      "avg_position": 0.0,
      "desktop_tablet_impressions": 0,
      "desktop_tablet_clicks": 0,
      "desktop_tablet_ctr": 0.0,
      "desktop_tablet_avg_position": 0.0,
      "mobile_impressions": 0,
      "mobile_clicks": 0,
      "mobile_ctr": 0.0,
      "mobile_avg_position": 0.0
    }
  ],
  "opportunities": {
    "mobile": [
      {
        "position": 0,
        "additional_clicks": 0.0,
        "target_ctr": 0.0,
        "current_ctr": 0.0
      }
    ],
    "desktop": [
      {
        "position": 0,
        "additional_clicks": 0.0,
        "target_ctr": 0.0,
        "current_ctr": 0.0
      }
    ]
  },
  "opportunities_explanations": "string"
}

Type Definitions

4 types

These are the available sub-object types that can be used in the properties above.

CTRDataPoint object
#
avg_position integer required

Average ranking position

device string required

Device type

nb_urls integer required

Number of URLs

pct_urls_with_clicks number required

Percentage of URLs with clicks

impressions integer required

Total impressions

clicks integer required

Total clicks

ctr_global number required

Global CTR

DeviceOpportunity object
#
position integer required

Target ranking position

additional_clicks number required

Additional clicks expected at this position

target_ctr number required

Expected CTR at target position (as %)

current_ctr number required

Current CTR (as %)

FilteredCTRMetrics object
#
impressions integer required
clicks integer required
ctr number | null required
avg_position number | null required
desktop_tablet_impressions integer required
desktop_tablet_clicks integer required
desktop_tablet_ctr number | null required
desktop_tablet_avg_position number | null required
mobile_impressions integer required
mobile_clicks integer required
mobile_ctr number | null required
mobile_avg_position number | null required
OpportunitiesByDevice object
#
mobile array required

Opportunities for mobile devices

Items: DeviceOpportunity

desktop array required

Opportunities for desktop devices

Items: DeviceOpportunity

Endpoints

POST http://agents.botify.com/{organization}/{project}/google_position_opportunities/process
POST http://agents.botify.com/{organization}/{project}/google_position_opportunities/batch_process
POST http://agents.botify.com/{organization}/{project}/google_position_opportunities/async_process
POST http://agents.botify.com/{organization}/{project}/google_position_opportunities/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/google_position_opportunities/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "period": "<period>"
  }
}'

Raw metadata