bisibility

package module
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

Bisibility Go SDK

Part of bisibility - open-source keyword rank tracking you can self-host and automate. This repository contains the Go SDK for the Bisibility REST API.

Docs · API reference · Roadmap

Status: Published as v0.5.0.

Idiomatic Go client for the Bisibility REST API.

The canonical SDK behavior contract defines the shared authentication, timeout, retry, cancellation, error, header, and cursor semantics implemented by this client.

Install

go get bisibility.com/sdk-go

Quickstart

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bisibility "bisibility.com/sdk-go"
)

func main() {
	ctx := context.Background()

	client, err := bisibility.NewClient(
		bisibility.WithAPIKey(os.Getenv("BISIBILITY_API_KEY")),
	)
	if err != nil {
		log.Fatal(err)
	}

	projects, err := client.ListProjects(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if len(projects.Data) == 0 {
		return
	}

	created, err := client.CreateKeywords(ctx, projects.Data[0].ID, bisibility.CreateKeywordsInput{
		Keywords: []bisibility.CreateKeywordInput{
			{
				Keyword:   "rank tracker api",
				TargetURL: ptr("https://example.com/rank-tracker"),
				Tags:      []string{"api"},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	if len(created.Results) == 0 {
		return
	}

	check, err := client.RunRankCheck(ctx, created.Results[0].Keyword.ID, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("position=%v url=%v\n", check.Position, check.RankingURL)
}

func ptr(value string) *string {
	return &value
}

Configuration

client, err := bisibility.NewClient(
	bisibility.WithAPIKey("bsb_key_live_..."),
	bisibility.WithBaseURL("https://bisibility.com/api/v1"),
	bisibility.WithMaxRetries(2),
)

WithBaseURL should point at the API v1 root. Protected methods send Authorization: Bearer <apiKey>. Write methods accept bisibility.WithIdempotencyKey("..."), which maps to the server Idempotency-Key header.

The client accepts project API keys (bsb_key_live_... or bsb_key_test_...) and personal access tokens (bsb_pat_live_...). Retired bsk_ and bsp_ credentials are rejected locally. For a PAT with multiple project memberships, pass a project ID returned by ListProjects to bisibility.WithProjectID(projectID). The client sends it as X-Bisibility-Project on project-implicit routes. PAT methods include GetMe, CreateProject, token self-management, project API-key minting, and webhook CRUD.

Public identifiers

All typed resource IDs accepted by client methods are strict public ID v3 values: prefix_[a-z][a-z0-9]{23}. The SDK rejects raw database IDs, legacy IDs, and mixed-case values before it sends an HTTP request. Use ValidatePublicID or ValidatePublicIDPrefix when validating values before calling the client.

The registered namespaces are al, alr, audit, check, cmp, conn, dwh, ferry, imp, inv, key, kw, mbr, ntf, pat, prj, sid, sig, svkw, tag, usr, viw, and we. Provider IDs and location_key values are not public resource IDs. Migration-token secrets are credentials, while ferry_ identifies the migration-token resource.

The examples below reuse projectID and keywordID values returned by the API, as shown in the quickstart, instead of embedding synthetic resource IDs.

Defaults
  • Every request sends X-Bisibility-Client: bisibility-sdk-go/<version> and the same value as User-Agent (bisibility.Version). Override the user agent with bisibility.WithDefaultHeader("User-Agent", "...") or per request with bisibility.WithRequestHeader.
  • The default HTTP client uses a 30 second timeout. Supply your own client with bisibility.WithHTTPClient(&http.Client{...}) to change the timeout, transport, or proxy behavior.
  • Idempotent requests retry network errors and HTTP 429/503 responses twice by default. GET, HEAD, PUT, and DELETE are idempotent, as is any request carrying WithIdempotencyKey. Backoff starts at 500ms and honors Retry-After up to 60 seconds. WithMaxRetries(0) disables retries, and context cancellation interrupts retry sleeps.
Async rank checks

RunRankCheck waits for the check by default. Set Async: true to enqueue the check instead; the API responds 202 Accepted with a rank check in status running, which you can poll with GetRankCheckResult:

check, err := client.RunRankCheck(ctx, keywordID, &bisibility.RunRankCheckInput{Async: true})
Public cost estimates

GetProviderRates and GetCostEstimate are public like the discovery methods and send no Authorization header:

rates, err := client.GetProviderRates(ctx)

estimate, err := client.GetCostEstimate(ctx, bisibility.CostEstimateOptions{
	Keywords:  248,
	Frequency: bisibility.EstimateFrequencyDaily,
	Provider:  bisibility.ProviderIDDataForSEO,
	Option:    "standard",
})
fmt.Printf("monthly cost: $%.2f\n", estimate.Data.MonthlyCostUSD)

Flat rate cards (PricingModel flat) carry Options; plan rate cards (plan) carry Plans.

Signals

CreateSignal ingests deploy, CMS, or API events for the API key's project, and ListSignals pages through them newest first:

signal, err := client.CreateSignal(ctx, bisibility.CreateSignalInput{
	Source:  bisibility.SignalSourceDeploy,
	Type:    "deploy.completed",
	URL:     "https://example.com/releases/42",
	Payload: bisibility.JSONValue{"version": "1.2.3"},
})

signals, err := client.ListSignals(ctx, projectID, &bisibility.ListSignalsOptions{
	Source: bisibility.SignalSourceDeploy,
	From:   time.Now().AddDate(0, 0, -7),
})

CreateSignal only accepts the deploy, cms, and api sources; the other SignalSource values are emitted by Bisibility and only appear in list responses and list filters. Payloads must serialize to 8KB or less.

Keyword research and metrics

ResearchKeywords runs one paid, cached DataForSEO Labs lookup for a single seed. Choose a research mode and a result limit of 100, 300, or 500 before the request. There is no offset pagination. IncludeClickstream requests clickstream-refined metrics and increases provider cost. Use EstimateOnly for a free, cache-aware dry run and MaxCostCents for a best-effort request guard. Partial auto-mode responses identify each source as ok, failed, or skipped with an optional machine-readable reason. This method requires an API key with write scope.

research, err := client.ResearchKeywords(ctx, projectID, bisibility.ResearchKeywordsOptions{
	Seed:         "rank tracker",
	Mode:         bisibility.KeywordResearchModeAuto,
	ResultLimit:  100,
	MaxCostCents: 5,
})

GetKeywordMetrics hydrates nullable volume, CPC, competition, difficulty, intent, and monthly trend data for up to 700 keywords. The API caches each keyword independently and fetches only cache misses unless Fresh is set. Split larger inputs into requests of at most 700 keywords. Set EstimateOnly to inspect CachedCount, FetchedCountEstimate, and EstimatedCostCents without spending. MaxCostCents rejects a paid lookup whose estimate is too high. This method requires an API key with write scope.

metrics, err := client.GetKeywordMetrics(ctx, projectID, bisibility.GetKeywordMetricsInput{
	Keywords: []string{"rank tracker", "seo api"},
})
Saved keywords

CreateSavedKeywords persists researched keywords on a project so they survive the research cache. Only Keyword is required; the API substitutes the project default market when Location is empty and reports keywords already saved or tracked as skipped instead of failing the request. Saved keywords carry svkw_ public IDs and nullable provider metrics:

saved, err := client.CreateSavedKeywords(ctx, projectID, bisibility.CreateSavedKeywordsInput{
	Keywords: []bisibility.SavedKeywordItem{
		bisibility.SavedKeywordText("rank tracker"),
		bisibility.SavedKeywordInput{Keyword: "seo api", SourceSeed: "rank tracker"},
	},
})
fmt.Printf("saved %d, duplicates %d\n", saved.SavedCount, saved.DuplicateCount)

keywords, err := client.ListSavedKeywords(ctx, projectID, nil)

removed, err := client.DeleteProjectSavedKeyword(ctx, projectID, savedKeywordID)
Domain overview

AnalyzeDomainOverview returns either a cache-aware estimate or a report with core metrics plus ranked-keyword and relevant-page module outcomes. Estimate first, then pass an explicit MaxCostCents pointer before any request that may spend provider budget. A zero cap makes the operation cache-only. Fresh bypasses caches but never removes the explicit cap requirement.

estimateOnly := true
estimate, err := client.AnalyzeDomainOverview(ctx, projectID, bisibility.AnalyzeDomainOverviewOptions{
	Target:       "example.com",
	LocationCode: 2840,
	LanguageCode: "en",
	EstimateOnly: &estimateOnly,
})
if err != nil {
	log.Fatal(err)
}
if estimate.Data.Estimate == nil {
	log.Fatal("expected an estimate")
}

maxCost := 10
report, err := client.AnalyzeDomainOverview(ctx, projectID, bisibility.AnalyzeDomainOverviewOptions{
	Target:       "example.com",
	LocationCode: 2840,
	LanguageCode: "en",
	MaxCostCents: &maxCost,
})
if err != nil {
	log.Fatal(err)
}
if report.Data.Report != nil {
	fmt.Printf("state=%s charged=%.4f cents\n", report.Data.Report.State, report.Data.Report.CostCents)
}

LoadDomainOverviewHistory, LoadDomainOverviewKeywords, and LoadDomainOverviewPages load separately priced modules for an unexpired overview snapshot. Every input includes a required MaxCostCents field, with zero used for cache-only attempts. The API returns failed top-level operations as RFC problem responses; partial analysis reports keep typed success or failure outcomes on their nested keyword and page modules. Decode APIError.Problem.Errors into DomainOverviewProblemErrors when callers need the failure reason, charged cost, or reset time.

Methods

  • Discovery: GetHealth, GetLiveness, GetReadiness, GetOpenAPI, GetCapabilities, GetLLMSText
  • Public cost: GetProviderRates, GetCostEstimate
  • Projects: ListProjects, Projects, GetProject, UpdateProject, DeleteProject, UpdateProjectDefaults
  • API keys: ListAPIKeys, CreateAPIKey, RevokeAPIKey
  • Keywords: ListKeywords, KeywordsList, CreateKeywords, KeywordsCreate, AddKeywords, GetKeyword, UpdateKeyword, SetKeywordTargetURL, DeleteKeyword, BulkUpdateKeywords, ResearchKeywords, GetKeywordMetrics
  • Rank checks: ListRankChecks, RankHistory, ExportRankHistory, IterateRankHistory, RunRankCheck, RunCheck, GetRankCheckResult
  • Alert rules: ListAlertRules, CreateAlertRule, UpdateAlertRule, DeleteAlertRule, ListTriggeredAlerts, MuteTriggeredAlert, MarkProjectAlertsRead
  • Team: ListTeamMembers, ListTeamInvites, CreateTeamInvite, RevokeTeamInvite, RevokeProjectTeamInvite
  • Providers: ListProviders, ConnectProvider, TestProviderConnection, UpdateProviderSettings, SetProviderEnabled, SetProviderPriority, SetPrimaryProvider, DisconnectProvider
  • Saved keywords: ListSavedKeywords, IterateSavedKeywords, CreateSavedKeywords, DeleteProjectSavedKeyword
  • Domain overview: AnalyzeDomainOverview, LoadDomainOverviewHistory, LoadDomainOverviewKeywords, LoadDomainOverviewPages
  • Saved views: ListSavedViews, CreateSavedView, DeleteSavedView, DeleteProjectSavedView
  • Competitors: ListCompetitors, AddCompetitor, RemoveCompetitor, RemoveProjectCompetitor
  • Notification preferences: GetNotificationPreferences, UpdateNotificationPreferences
  • Migration tokens: ListMigrationTokens, MintMigrationToken, RevokeMigrationToken, RevokeProjectMigrationToken
  • Cloud import: GetCloudImportCompatibility, ImportCloudExport, CreateCloudImportSession, UploadCloudImportChunk, UploadCloudImportChunkRaw, FinalizeCloudImportSession
  • Signals: CreateSignal, ListSignals
  • Sitemap monitors: ListSitemapMonitors, UpdateSitemapMonitor

List methods return ListResponse[T] with Meta.NextCursor. Resource methods return typed resources. Cursor values are opaque: pass v3 API cursors back unchanged.

ExportRankHistory returns a cursor-paginated JSON page by default. Set Format: bisibility.RankHistoryExportFormatCSV to receive the complete CSV document in the response's CSV field.

Go 1.22 consumers can traverse every cursor list with the corresponding Iterate* method and a Pager. Filters remain unchanged between pages:

pager := client.IterateKeywords(ctx, projectID, &bisibility.ListKeywordsOptions{Tag: "api"})
for pager.Next() {
	keyword := pager.Item()
	fmt.Println(keyword.Text)
}
if err := pager.Err(); err != nil {
	log.Fatal(err)
}

Pagers cover keywords, rank checks, signals, API keys including project API keys, webhooks, alert rules, triggered alerts, team members, team invites, providers, saved views, competitors, and migration tokens.

ListKeywords filters include Intent and Topic (case-insensitive exact matches, sent as filter[intent] and filter[topic]). Provider methods accept the connectable provider ids dataforseo, serpapi, gsc, ga4, and plausible (bisibility.ProviderIDPlausible); self-hosted providers such as Plausible take their instance URL via ProviderCredentialsInput.Endpoint.

Some list endpoints expose typed metadata beyond pagination. ListCompetitors returns ListCompetitorsResponse with markets and suggestions, and ListMigrationTokens returns ListMigrationTokensResponse with import job status.

Cloud-import writes authenticate with a migration token minted by MintMigrationToken, passed as the first argument rather than through the client API key. GetCloudImportCompatibility is an unauthenticated preflight. The SDK supports only protocol version 5 and writes that discriminator itself. CloudImportPackage requires project_id plus non-nil keywords, alert_rules, competitors, notification_preferences, and saved_views collections. CreateCloudImportSession requires a strict source_project_id. Although the route still says sessions, the returned ID and every chunk or finalize path use the strict imp_ public-ID namespace.

UploadCloudImportChunk accepts either CloudImportKeywordsChunk or CloudImportSectionsChunk, so the kind discriminator is fixed by the Go type. Alert-rule targets similarly use CloudImportKeywordAlertTarget or CloudImportTagAlertTarget. The SDK rejects v4 payloads, raw IDs, camel-case aliases for snake-case fields, and incomplete required shapes before sending a request. UploadCloudImportChunkRaw streams a pre-serialized JSON body from an io.Reader and can set Content-Encoding: gzip for a compressed chunk.

session, err := client.CreateCloudImportSession(ctx, migrationToken, bisibility.CloudImportSessionCreate{
	ChunkCount:      1,
	SourceProjectID: projectID,
})
if err != nil {
	log.Fatal(err)
}
_, err = client.UploadCloudImportChunk(ctx, migrationToken, session.SessionID, 0, bisibility.CloudImportKeywordsChunk{
	Checksum: "sha256:0000000000000000000000000000000000000000000000000000000000000000",
	Keywords: []bisibility.CloudImportKeyword{{
		ID:       keywordID,
		Keyword:  "rank tracker",
		Device:   bisibility.DeviceDesktop,
		Location: "United States",
	}},
})
if err != nil {
	log.Fatal(err)
}

Errors

All SDK-defined errors implement bisibility.BisibilityError. Non-2xx API responses return *bisibility.APIError; the original RFC problem details body is available on err.Problem. IsRateLimit, IsNotFound, and RetryAfter provide common status helpers. Sensitive response headers are removed before an API error is exposed.

keyword, err := client.GetKeyword(ctx, "kw_z9y8x7w6v5u4t3s2r1q0p9n8")
if err != nil {
	var apiErr *bisibility.APIError
	if errors.As(err, &apiErr) {
		log.Printf("status=%d detail=%s", apiErr.StatusCode, apiErr.Problem.Detail)
	}
	log.Fatal(err)
}
_ = keyword

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

Documentation

Overview

Package bisibility provides a Go client for the Bisibility API, including SEO rank tracking, keywords, and ranking history.

Index

Constants

View Source 
const CloudImportProtocolVersion = 5

CloudImportProtocolVersion is the only export-package protocol version supported by the cloud-import API.

View Source 
const Version = "0.9.0"

Version is the SDK version reported in the User-Agent header.

Variables

This section is empty.

Functions

func IsAPIError 

func IsAPIError(err error) bool

IsAPIError reports whether err is an APIError.

func IsPublicID added in v0.5.0 

func IsPublicID(value string) bool

IsPublicID reports whether value is a strict Bisibility public ID from the canonical registry. It intentionally rejects legacy IDs and raw database IDs.

func ValidatePublicID added in v0.5.0 

func ValidatePublicID(value string) error

ValidatePublicID validates a strict public ID from any registered namespace.

func ValidatePublicIDPrefix added in v0.5.0 

func ValidatePublicIDPrefix(value string, prefix PublicIDPrefix) error

ValidatePublicIDPrefix validates a strict public ID in one resource namespace.

Types

type APIError 

type APIError struct {
	Body       string
	Header     http.Header
	Method     string
	Problem    *ProblemDetails
	StatusCode int
	URL        string
}

APIError reports a non-2xx HTTP response from the Bisibility API.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) IsNotFound 

func (e *APIError) IsNotFound() bool

IsNotFound reports whether the API returned HTTP 404.

func (*APIError) IsRateLimit 

func (e *APIError) IsRateLimit() bool

IsRateLimit reports whether the API returned HTTP 429.

func (*APIError) RetryAfter 

func (e *APIError) RetryAfter() (time.Duration, bool)

RetryAfter parses Retry-After as delta seconds or an HTTP date, capped at 60 seconds.

type APIKey 

type APIKey struct {
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	Prefix     string     `json:"prefix"`
	CreatedAt  time.Time  `json:"created_at"`
	LastUsedAt *time.Time `json:"last_used_at"`
	RevokedAt  *time.Time `json:"revoked_at"`
}

APIKey describes an API key without the raw token.

type AddCompetitorInput 

type AddCompetitorInput struct {
	Domain string `json:"domain"`
	Label  string `json:"label,omitempty"`
}

AddCompetitorInput adds a managed competitor to a project.

type AlertChannel 

type AlertChannel string

AlertChannel identifies a delivery channel for alert rules. 

const (
	AlertChannelEmail   AlertChannel = "email"
	AlertChannelSlack   AlertChannel = "slack"
	AlertChannelWebhook AlertChannel = "webhook"
)

type AlertConditionType 

type AlertConditionType string

AlertConditionType identifies the condition used by an alert rule. 

const (
	AlertConditionTypeThreshold          AlertConditionType = "threshold"
	AlertConditionTypeChangePct          AlertConditionType = "change_pct"
	AlertConditionTypeEntersTopN         AlertConditionType = "enters_top_n"
	AlertConditionTypeExitsTopN          AlertConditionType = "exits_top_n"
	AlertConditionTypeCompetitorOvertake AlertConditionType = "competitor_overtake"
	AlertConditionTypeSERPFeature        AlertConditionType = "serp_feature"
)

type AlertRule 

type AlertRule struct {
	ID                string             `json:"id"`
	Name              string             `json:"name"`
	Channel           string             `json:"channel,omitempty"`
	Channels          []AlertChannel     `json:"channels,omitempty"`
	ChangePct         *FlexibleFloat     `json:"change_pct,omitempty"`
	Condition         string             `json:"condition,omitempty"`
	ConditionType     AlertConditionType `json:"condition_type,omitempty"`
	CompetitorDomain  *string            `json:"competitor_domain,omitempty"`
	CreatedAt         *time.Time         `json:"created_at,omitempty"`
	Enabled           bool               `json:"enabled"`
	Fires             string             `json:"fires,omitempty"`
	Period            string             `json:"period,omitempty"`
	RecipientIDs      []string           `json:"recipient_ids"`
	Scope             string             `json:"scope,omitempty"`
	SERPFeature       *string            `json:"serp_feature,omitempty"`
	Severity          AlertSeverity      `json:"severity,omitempty"`
	Status            AlertRuleStatus    `json:"status,omitempty"`
	TargetIDs         []string           `json:"target_ids,omitempty"`
	TargetType        AlertTargetType    `json:"target_type,omitempty"`
	ThresholdPosition *int               `json:"threshold_position,omitempty"`
	TopN              *int               `json:"top_n,omitempty"`
	UpdatedAt         *time.Time         `json:"updated_at,omitempty"`
}

AlertRule is an alert rule returned by list, create, and update endpoints.

type AlertRuleDeleteResult 

type AlertRuleDeleteResult struct {
	Deleted bool `json:"deleted"`
}

AlertRuleDeleteResult is returned after deleting an alert rule.

type AlertRuleStatus 

type AlertRuleStatus string

AlertRuleStatus is the display status of an alert rule. 

const (
	AlertRuleStatusActive   AlertRuleStatus = "active"
	AlertRuleStatusPaused   AlertRuleStatus = "paused"
	AlertRuleStatusLearning AlertRuleStatus = "learning"
	AlertRuleStatusSetup    AlertRuleStatus = "setup"
)

type AlertSeverity 

type AlertSeverity string

AlertSeverity is the severity shown for alert rules and triggered alerts. 

const (
	AlertSeverityUrgent  AlertSeverity = "urgent"
	AlertSeverityWarning AlertSeverity = "warning"
	AlertSeverityInfo    AlertSeverity = "info"
)

type AlertTargetType 

type AlertTargetType string

AlertTargetType identifies the target set for an alert rule. 

const (
	AlertTargetTypeAll     AlertTargetType = "all"
	AlertTargetTypeKeyword AlertTargetType = "keyword"
	AlertTargetTypeTag     AlertTargetType = "tag"
)

type AnalyticsConnection 

type AnalyticsConnection struct {
	ID       string `json:"id"`
	Label    string `json:"label"`
	Provider string `json:"provider"`
}

AnalyticsConnection identifies the selected project-owned analytics connection.

type AnalyzeBacklinksOptions added in v0.4.0 

type AnalyzeBacklinksOptions struct {
	Target            string
	TargetScope       BacklinkTargetScope
	IncludeSubdomains bool
	ResultLimit       int
	Mode              BacklinkMode
	EstimateOnly      bool
	Fresh             bool
	MaxCostCents      int
}

AnalyzeBacklinksOptions controls a paid or estimated backlink analysis.

type AnalyzeDomainOverviewOptions added in v0.8.0 

type AnalyzeDomainOverviewOptions struct {
	Target        string               `json:"target"`
	LocationCode  int                  `json:"location_code"`
	LanguageCode  string               `json:"language_code"`
	ScopeOverride *DomainOverviewScope `json:"scope_override,omitempty"`
	Fresh         *bool                `json:"fresh,omitempty"`
	MaxCostCents  *int                 `json:"max_cost_cents,omitempty"`
	EstimateOnly  *bool                `json:"estimate_only,omitempty"`
	KeywordLimit  *int                 `json:"keyword_limit,omitempty"`
	PageLimit     *int                 `json:"page_limit,omitempty"`
}

AnalyzeDomainOverviewOptions controls a cache-aware estimate or domain overview analysis.

type BacklinkMode added in v0.4.0 

type BacklinkMode string

BacklinkMode controls provider-side row grouping over the full backlink corpus. 

const (
	BacklinkModeAsIs         BacklinkMode = "as_is"
	BacklinkModeOnePerDomain BacklinkMode = "one_per_domain"
)

type BacklinkRow added in v0.4.0 

type BacklinkRow struct {
	Anchor          string         `json:"anchor"`
	DomainAuthority int            `json:"domain_authority"`
	FirstSeen       string         `json:"first_seen"`
	Flags           []string       `json:"flags"`
	LinksCount      int            `json:"links_count"`
	LostAt          *string        `json:"lost_at"`
	SourceDomain    string         `json:"source_domain"`
	SourceURL       string         `json:"source_url"`
	SpamScore       float64        `json:"spam_score"`
	Status          BacklinkStatus `json:"status"`
	TargetURL       string         `json:"target_url"`
}

BacklinkRow describes one backlink returned in a snapshot.

type BacklinkStatus added in v0.4.0 

type BacklinkStatus string

BacklinkStatus describes whether a backlink is active, newly discovered, or lost. 

const (
	BacklinkStatusActive BacklinkStatus = "active"
	BacklinkStatusNew    BacklinkStatus = "new"
	BacklinkStatusLost   BacklinkStatus = "lost"
)

type BacklinkTargetScope added in v0.4.0 

type BacklinkTargetScope string

BacklinkTargetScope selects a whole site or one page as the backlink target. 

const (
	BacklinkTargetScopeSite BacklinkTargetScope = "site"
	BacklinkTargetScopePage BacklinkTargetScope = "page"
)

type BacklinksHistoryMonth added in v0.4.0 

type BacklinksHistoryMonth struct {
	LostLinks int    `json:"lost_links"`
	Month     string `json:"month"`
	NewLinks  int    `json:"new_links"`
}

BacklinksHistoryMonth contains backlink gains and losses for one calendar month.

type BacklinksSnapshot added in v0.4.0 

type BacklinksSnapshot struct {
	Cached             bool                    `json:"cached"`
	CachedUntil        time.Time               `json:"cached_until"`
	CostCents          float64                 `json:"cost_cents"`
	Estimate           *bool                   `json:"estimate,omitempty"`
	EstimatedCostCents *float64                `json:"estimated_cost_cents,omitempty"`
	FetchedAt          time.Time               `json:"fetched_at"`
	FetchedRowCount    int                     `json:"fetched_row_count"`
	History            []BacklinksHistoryMonth `json:"history"`
	IncludeSubdomains  bool                    `json:"include_subdomains"`
	Provider           string                  `json:"provider"`
	Rows               []BacklinkRow           `json:"rows"`
	Summary            BacklinksSummary        `json:"summary"`
	Target             string                  `json:"target"`
	TargetScope        BacklinkTargetScope     `json:"target_scope"`
	TotalRowsAvailable int                     `json:"total_rows_available"`
}

BacklinksSnapshot is one cached, paid, or estimated backlink analysis result.

type BacklinksSnapshotResponse added in v0.4.0 

type BacklinksSnapshotResponse = DataResponse[BacklinksSnapshot]

BacklinksSnapshotResponse wraps a backlinks snapshot in the public API data envelope.

type BacklinksSummary added in v0.4.0 

type BacklinksSummary struct {
	BacklinksTotal        int     `json:"backlinks_total"`
	BrokenBacklinks       int     `json:"broken_backlinks"`
	BrokenPages           int     `json:"broken_pages"`
	DofollowPct           float64 `json:"dofollow_pct"`
	DomainRank            int     `json:"domain_rank"`
	LostBacklinks         int     `json:"lost_backlinks"`
	LostReferringDomains  int     `json:"lost_referring_domains"`
	NewBacklinks          int     `json:"new_backlinks"`
	NewReferringDomains   int     `json:"new_referring_domains"`
	ReferringDomainsTotal int     `json:"referring_domains_total"`
	ReferringPages        int     `json:"referring_pages"`
	SpamScore             float64 `json:"spam_score"`
}

BacklinksSummary contains provider totals for a backlinks snapshot.

type BisibilityError 

type BisibilityError interface {
	error
	// contains filtered or unexported methods
}

BisibilityError is implemented by every SDK-defined error.

type Capability 

type Capability struct {
	Name        string    `json:"name"`
	OperationID string    `json:"operationId"`
	Description string    `json:"description"`
	InputSchema JSONValue `json:"input_schema"`
}

Capability describes an API capability advertised by Bisibility.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client calls the Bisibility REST API.

func NewClient 

func NewClient(options ...Option) (*Client, error)

NewClient creates a Bisibility API client.

func (*Client) AddCompetitor 

func (c *Client) AddCompetitor(ctx context.Context, projectID string, input AddCompetitorInput, options ...RequestOption) (*Competitor, error)

AddCompetitor adds a managed competitor to a project.

func (*Client) AddKeywords 

func (c *Client) AddKeywords(ctx context.Context, projectID string, keywords []CreateKeywordInput, options ...RequestOption) (*CreateKeywordsResponse, error)

AddKeywords posts an array of keyword creation items. 

func (c *Client) AnalyzeBacklinks(ctx context.Context, projectID string, input AnalyzeBacklinksOptions, options ...RequestOption) (*BacklinksSnapshotResponse, error)

AnalyzeBacklinks analyzes a backlink target or returns a free estimate-only dry run. The endpoint requires write scope because cache misses can spend provider budget.

func (*Client) AnalyzeDomainOverview added in v0.8.0 

func (c *Client) AnalyzeDomainOverview(ctx context.Context, projectID string, input AnalyzeDomainOverviewOptions, options ...RequestOption) (*DomainOverviewAnalyzeResponse, error)

AnalyzeDomainOverview estimates or loads a domain overview report. Non-estimate calls can spend provider budget and require an explicit maximum cost.

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the configured API v1 root URL.

func (*Client) BulkUpdateKeywords 

func (c *Client) BulkUpdateKeywords(ctx context.Context, input KeywordBulkInput, options ...RequestOption) (*KeywordBulkResponse, error)

BulkUpdateKeywords mutates many keywords.

func (*Client) ConnectProvider 

func (c *Client) ConnectProvider(ctx context.Context, projectID string, providerID ProviderID, input ConnectProviderInput, options ...RequestOption) (*ProviderConnection, error)

ConnectProvider connects or updates credentials for a project provider.

func (*Client) CreateAPIKey 

func (c *Client) CreateAPIKey(ctx context.Context, input CreateAPIKeyInput, options ...RequestOption) (*CreatedAPIKey, error)

CreateAPIKey creates an API key for the configured API key's project.

func (*Client) CreateAlertRule 

func (c *Client) CreateAlertRule(ctx context.Context, projectID string, input CreateAlertRuleInput, options ...RequestOption) (*AlertRule, error)

CreateAlertRule creates an alert rule for a project.

func (*Client) CreateCloudImportSession 

func (c *Client) CreateCloudImportSession(ctx context.Context, migrationToken string, input CloudImportSessionCreate, options ...RequestOption) (*CloudImportSessionCreateResponse, error)

CreateCloudImportSession opens a chunked cloud-import session, authenticated with a migration token. Upload each chunk with UploadCloudImportChunk, then complete the import with FinalizeCloudImportSession.

func (*Client) CreateKeywords 

func (c *Client) CreateKeywords(ctx context.Context, projectID string, input CreateKeywordsInput, options ...RequestOption) (*CreateKeywordsResponse, error)

CreateKeywords creates one or more keywords using the wrapped API body shape.

func (*Client) CreateMyToken 

func (c *Client) CreateMyToken(ctx context.Context, input CreateMyTokenInput, options ...RequestOption) (*CreatedPersonalAccessToken, error)

CreateMyToken mints a personal access token. The raw bsb_pat_ secret is only returned once in the Token field. Requires a personal access token with admin tier or an OAuth access token bearing the tokens:write scope.

func (*Client) CreateProject 

func (c *Client) CreateProject(ctx context.Context, input CreateProjectInput, options ...RequestOption) (*Project, error)

CreateProject creates a project. Requires a personal access token with write tier; project-scoped API keys cannot create projects.

func (*Client) CreateProjectAPIKey 

func (c *Client) CreateProjectAPIKey(ctx context.Context, projectID string, input CreateAPIKeyInput, options ...RequestOption) (*CreatedAPIKey, error)

CreateProjectAPIKey mints a project API key using the nested route. The raw bsb_key_ secret is only returned once in the Token field.

func (*Client) CreateSavedKeywords added in v0.6.0 

func (c *Client) CreateSavedKeywords(ctx context.Context, projectID string, input CreateSavedKeywordsInput, options ...RequestOption) (*CreateSavedKeywordsResult, error)

CreateSavedKeywords saves research keywords for a project. Keywords already saved are reported as duplicates instead of failing the request.

func (*Client) CreateSavedView 

func (c *Client) CreateSavedView(ctx context.Context, projectID string, input CreateSavedViewInput, options ...RequestOption) (*SavedView, error)

CreateSavedView creates a keyword saved view for a project.

func (*Client) CreateSignal 

func (c *Client) CreateSignal(ctx context.Context, input CreateSignalInput, options ...RequestOption) (*Signal, error)

CreateSignal ingests a signal for the API key's project. The API responds 201 with the created signal resource.

func (*Client) CreateTeamInvite 

func (c *Client) CreateTeamInvite(ctx context.Context, projectID string, input CreateTeamInviteInput, options ...RequestOption) (*CreatedTeamInvite, error)

CreateTeamInvite creates a team invite for a project.

func (*Client) CreateWebhook 

func (c *Client) CreateWebhook(ctx context.Context, projectID string, input CreateWebhookInput, options ...RequestOption) (*Webhook, error)

CreateWebhook creates a webhook for a project.

func (*Client) DeleteAlertRule 

func (c *Client) DeleteAlertRule(ctx context.Context, ruleID string, options ...RequestOption) (*AlertRuleDeleteResult, error)

DeleteAlertRule deletes an alert rule by ID.

func (*Client) DeleteKeyword 

func (c *Client) DeleteKeyword(ctx context.Context, keywordID string, options ...RequestOption) (*Keyword, error)

DeleteKeyword deletes one keyword and returns the deleted resource when the API sends one.

func (*Client) DeleteProject 

func (c *Client) DeleteProject(ctx context.Context, projectID string, options ...RequestOption) (*Project, error)

DeleteProject deletes one project and returns the deleted resource.

func (*Client) DeleteProjectSavedKeyword added in v0.6.0 

func (c *Client) DeleteProjectSavedKeyword(ctx context.Context, projectID, savedKeywordID string, options ...RequestOption) (*SavedKeywordDeleteResult, error)

DeleteProjectSavedKeyword deletes a saved keyword by project and saved keyword ID.

func (*Client) DeleteProjectSavedView 

func (c *Client) DeleteProjectSavedView(ctx context.Context, projectID, viewID string, options ...RequestOption) (*SavedViewDeleteResult, error)

DeleteProjectSavedView deletes a saved view by project and view ID.

func (*Client) DeleteSavedView 

func (c *Client) DeleteSavedView(ctx context.Context, viewID string, options ...RequestOption) (*SavedViewDeleteResult, error)

DeleteSavedView deletes a saved view by ID using the top-level route.

func (*Client) DeleteWebhook 

func (c *Client) DeleteWebhook(ctx context.Context, projectID, webhookID string, options ...RequestOption) (*Webhook, error)

DeleteWebhook deletes a webhook by project and webhook ID and returns the deleted resource. Requires admin tier.

func (*Client) DisconnectProvider 

func (c *Client) DisconnectProvider(ctx context.Context, projectID string, providerID ProviderID, options ...RequestOption) (*ProviderDisconnectResult, error)

DisconnectProvider disconnects a provider from a project.

func (*Client) ExportRankHistory 

func (c *Client) ExportRankHistory(ctx context.Context, projectID string, input *ExportRankHistoryOptions, options ...RequestOption) (*RankHistoryExportResponse, error)

ExportRankHistory returns a cursor-paginated JSON page or the complete CSV export. Set Format to RankHistoryExportFormatCSV for CSV. CSV responses are not paginated.

func (*Client) FinalizeCloudImportSession 

func (c *Client) FinalizeCloudImportSession(ctx context.Context, migrationToken, sessionID string, options ...RequestOption) (*CloudImportFinalizeResponse, error)

FinalizeCloudImportSession finalizes a chunked import session after every chunk has been uploaded, authenticated with a migration token. The API responds 200 with the completed import counts.

func (*Client) GetCapabilities 

func (c *Client) GetCapabilities(ctx context.Context, options ...RequestOption) (*DataResponse[[]Capability], error)

GetCapabilities returns the public capabilities envelope.

func (*Client) GetCloudImportCompatibility 

func (c *Client) GetCloudImportCompatibility(ctx context.Context, options ...RequestOption) (*CloudImportCompatibility, error)

GetCloudImportCompatibility checks cloud-import schema compatibility. It is an unauthenticated preflight that reports which package schema versions the server accepts before a migration begins.

func (*Client) GetCostEstimate 

func (c *Client) GetCostEstimate(ctx context.Context, input CostEstimateOptions, options ...RequestOption) (*DataResponse[CostEstimate], error)

GetCostEstimate estimates the monthly SERP provider cost for a keyword portfolio using public rate cards. No API key is required. The request is sent anonymously: any Authorization header set via WithDefaultHeader or WithRequestHeader is stripped before sending. Keywords is always sent; zero-valued optional fields fall back to server defaults.

func (*Client) GetHealth 

func (c *Client) GetHealth(ctx context.Context, options ...RequestOption) (*HealthResponse, error)

GetHealth returns public API health information.

func (*Client) GetKeyword 

func (c *Client) GetKeyword(ctx context.Context, keywordID string, options ...RequestOption) (*Keyword, error)

GetKeyword fetches one keyword by public keyword ID.

func (*Client) GetKeywordMetrics 

func (c *Client) GetKeywordMetrics(ctx context.Context, projectID string, input GetKeywordMetricsInput, options ...RequestOption) (*KeywordMetricsResponse, error)

GetKeywordMetrics gets cached or paid provider metrics for up to 700 keywords. The endpoint requires an API key with write scope because cache misses can spend provider budget.

func (*Client) GetLLMSText 

func (c *Client) GetLLMSText(ctx context.Context, options ...RequestOption) (string, error)

GetLLMSText returns the public llms.txt document.

func (*Client) GetLiveness added in v0.6.0 

func (c *Client) GetLiveness(ctx context.Context, options ...RequestOption) (*LivenessResponse, error)

GetLiveness reports whether the web process is alive.

func (*Client) GetMe 

func (c *Client) GetMe(ctx context.Context, options ...RequestOption) (*Me, error)

GetMe returns the authenticated user and project memberships. Only personal access tokens (bsb_pat_) may call this method.

func (*Client) GetNotificationPreferences 

func (c *Client) GetNotificationPreferences(ctx context.Context, projectID string, options ...RequestOption) (*NotificationPreferences, error)

GetNotificationPreferences gets project notification preferences for the current user.

func (*Client) GetOpenAPI 

func (c *Client) GetOpenAPI(ctx context.Context, options ...RequestOption) (*OpenAPIDocument, error)

GetOpenAPI returns the public OpenAPI document.

func (*Client) GetProject 

func (c *Client) GetProject(ctx context.Context, projectID string, options ...RequestOption) (*Project, error)

GetProject fetches one project by public project ID.

func (*Client) GetProjectDefaults 

func (c *Client) GetProjectDefaults(ctx context.Context, projectID string, options ...RequestOption) (*ProjectDefaults, error)

GetProjectDefaults gets project default market and schedule settings.

func (*Client) GetProjectOverview added in v0.4.0 

func (c *Client) GetProjectOverview(ctx context.Context, projectID string, input *ProjectOverviewOptions, options ...RequestOption) (*ProjectOverview, error)

GetProjectOverview gets keyword rank performance for a project.

func (*Client) GetProviderRates 

func (c *Client) GetProviderRates(ctx context.Context, options ...RequestOption) (*DataResponse[[]ProviderRate], error)

GetProviderRates returns the public SERP provider rate cards. No API key is required. The request is sent anonymously: any Authorization header set via WithDefaultHeader or WithRequestHeader is stripped before sending.

func (*Client) GetRankCheckResult 

func (c *Client) GetRankCheckResult(ctx context.Context, checkID string, options ...RequestOption) (*RankCheck, error)

GetRankCheckResult fetches one rank check by ID.

func (*Client) GetReadiness added in v0.6.0 

func (c *Client) GetReadiness(ctx context.Context, options ...RequestOption) (*ReadinessResponse, error)

GetReadiness reports whether the web process is ready to receive traffic.

func (*Client) ImportCloudExport 

func (c *Client) ImportCloudExport(ctx context.Context, migrationToken string, pkg CloudImportPackage, options ...RequestOption) (*CloudImportFinalizeResponse, error)

ImportCloudExport imports an export package in a single request, authenticated with a migration token minted by MintMigrationToken. The API responds 201 with the completed import counts.

func (*Client) IterateAPIKeys 

func (c *Client) IterateAPIKeys(ctx context.Context, pagination *PaginationOptions, options ...RequestOption) *Pager[APIKey]

IterateAPIKeys returns a pager over API keys.

func (*Client) IterateAlertRules 

func (c *Client) IterateAlertRules(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[AlertRule]

func (*Client) IterateCompetitors 

func (c *Client) IterateCompetitors(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[ManagedCompetitor]

IterateCompetitors returns a pager over managed project competitors.

func (*Client) IterateKeywords 

func (c *Client) IterateKeywords(ctx context.Context, projectID string, filters *ListKeywordsOptions, options ...RequestOption) *Pager[Keyword]

IterateKeywords returns a pager over project keywords while preserving filters.

func (*Client) IterateMigrationTokens 

func (c *Client) IterateMigrationTokens(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[MigrationToken]

IterateMigrationTokens returns a pager over active migration tokens.

func (*Client) IterateProjectAPIKeys 

func (c *Client) IterateProjectAPIKeys(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[APIKey]

IterateProjectAPIKeys returns a pager over project API keys.

func (*Client) IterateProviders 

func (c *Client) IterateProviders(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[Provider]

func (*Client) IterateRankChecks 

func (c *Client) IterateRankChecks(ctx context.Context, keywordID string, filters *ListRankChecksOptions, options ...RequestOption) *Pager[RankCheck]

IterateRankChecks returns a pager over keyword rank checks while preserving filters.

func (*Client) IterateRankHistory 

func (c *Client) IterateRankHistory(ctx context.Context, projectID string, filters *ExportRankHistoryOptions, options ...RequestOption) *Pager[RankHistoryExportRow]

IterateRankHistory returns a pager over the JSON rank-history export. CSV format is ignored because CSV exports are complete and not cursor-paginated.

func (*Client) IterateSavedKeywords added in v0.6.0 

func (c *Client) IterateSavedKeywords(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[SavedKeyword]

func (*Client) IterateSavedViews 

func (c *Client) IterateSavedViews(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[SavedView]

func (*Client) IterateSignals 

func (c *Client) IterateSignals(ctx context.Context, projectID string, filters *ListSignalsOptions, options ...RequestOption) *Pager[Signal]

IterateSignals returns a pager over project signals while preserving filters.

func (*Client) IterateTeamInvites 

func (c *Client) IterateTeamInvites(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[TeamInvite]

func (*Client) IterateTeamMembers 

func (c *Client) IterateTeamMembers(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[TeamMember]

func (*Client) IterateTriggeredAlerts 

func (c *Client) IterateTriggeredAlerts(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[TriggeredAlert]

func (*Client) IterateWebhooks 

func (c *Client) IterateWebhooks(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) *Pager[Webhook]

IterateWebhooks returns a pager over project webhooks.

func (*Client) KeywordsCreate 

func (c *Client) KeywordsCreate(ctx context.Context, projectID string, input CreateKeywordsInput, options ...RequestOption) (*CreateKeywordsResponse, error)

KeywordsCreate is an operation-style alias for CreateKeywords.

func (*Client) KeywordsList 

func (c *Client) KeywordsList(ctx context.Context, projectID string, filters *ListKeywordsOptions, options ...RequestOption) (*ListResponse[Keyword], error)

KeywordsList is an operation-style alias for ListKeywords.

func (*Client) ListAPIKeys 

func (c *Client) ListAPIKeys(ctx context.Context, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[APIKey], error)

ListAPIKeys lists API keys for the configured API key's project.

func (*Client) ListAlertRules 

func (c *Client) ListAlertRules(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[AlertRule], error)

ListAlertRules lists alert rules for a project.

func (*Client) ListCompetitors 

func (c *Client) ListCompetitors(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListCompetitorsResponse, error)

ListCompetitors lists managed competitors and market metadata for a project.

func (*Client) ListKeywords 

func (c *Client) ListKeywords(ctx context.Context, projectID string, filters *ListKeywordsOptions, options ...RequestOption) (*ListResponse[Keyword], error)

ListKeywords lists keywords for a project.

func (*Client) ListMigrationTokens 

func (c *Client) ListMigrationTokens(ctx context.Context, projectID string, options ...RequestOption) (*ListMigrationTokensResponse, error)

ListMigrationTokens lists active migration tokens and import job metadata for a project.

func (*Client) ListMyTokens 

func (c *Client) ListMyTokens(ctx context.Context, options ...RequestOption) (*ListResponse[PersonalAccessToken], error)

ListMyTokens lists the authenticated user's personal access tokens. Requires a personal access token with admin tier.

func (*Client) ListProjectAPIKeys 

func (c *Client) ListProjectAPIKeys(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[APIKey], error)

ListProjectAPIKeys lists API keys for a project using the nested route.

func (*Client) ListProjects 

func (c *Client) ListProjects(ctx context.Context, options ...RequestOption) (*ListResponse[Project], error)

ListProjects lists projects visible to the configured API key.

func (*Client) ListProviders 

func (c *Client) ListProviders(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[Provider], error)

ListProviders lists available and connected providers for a project.

func (*Client) ListRankChecks 

func (c *Client) ListRankChecks(ctx context.Context, keywordID string, filters *ListRankChecksOptions, options ...RequestOption) (*ListResponse[RankCheck], error)

ListRankChecks lists rank checks for a keyword.

func (*Client) ListRankedKeywordSuggestions 

func (c *Client) ListRankedKeywordSuggestions(ctx context.Context, projectID string, input *ListRankedKeywordSuggestionsOptions, options ...RequestOption) (*RankedKeywordSuggestionsResponse, error)

ListRankedKeywordSuggestions lists one cached or paid page of ranked keyword suggestions.

func (*Client) ListSavedKeywords added in v0.6.0 

func (c *Client) ListSavedKeywords(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[SavedKeyword], error)

ListSavedKeywords lists saved research keywords for a project.

func (*Client) ListSavedViews 

func (c *Client) ListSavedViews(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[SavedView], error)

ListSavedViews lists keyword saved views for a project.

func (*Client) ListSearchPerformanceQueryStats 

func (c *Client) ListSearchPerformanceQueryStats(ctx context.Context, projectID string, input ListSearchPerformanceQueryStatsOptions, options ...RequestOption) (*SearchPerformanceQueryStatsResponse, error)

ListSearchPerformanceQueryStats reads live query statistics from a project analytics connection.

func (*Client) ListSignals 

func (c *Client) ListSignals(ctx context.Context, projectID string, filters *ListSignalsOptions, options ...RequestOption) (*ListResponse[Signal], error)

ListSignals lists signals for a project, newest first.

func (*Client) ListSitemapMonitors 

func (c *Client) ListSitemapMonitors(ctx context.Context, projectID string, options ...RequestOption) (*ListResponse[SitemapMonitor], error)

ListSitemapMonitors lists the project sitemap monitor and latest snapshot.

func (*Client) ListTeamInvites 

func (c *Client) ListTeamInvites(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[TeamInvite], error)

ListTeamInvites lists pending team invites for a project.

func (*Client) ListTeamMembers 

func (c *Client) ListTeamMembers(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[TeamMember], error)

ListTeamMembers lists team members for a project.

func (*Client) ListTrafficSnapshots 

func (c *Client) ListTrafficSnapshots(ctx context.Context, projectID string, input ListTrafficSnapshotsOptions, options ...RequestOption) (*PageTrafficSnapshotsResponse, error)

ListTrafficSnapshots lists stored page analytics snapshots for an inclusive date range.

func (*Client) ListTriggeredAlerts 

func (c *Client) ListTriggeredAlerts(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[TriggeredAlert], error)

ListTriggeredAlerts lists triggered alert events for a project.

func (*Client) ListWebhooks 

func (c *Client) ListWebhooks(ctx context.Context, projectID string, pagination *PaginationOptions, options ...RequestOption) (*ListResponse[Webhook], error)

ListWebhooks lists webhooks for a project.

func (*Client) LoadDomainOverviewHistory added in v0.8.0 

func (c *Client) LoadDomainOverviewHistory(ctx context.Context, projectID string, input LoadDomainOverviewHistoryOptions, options ...RequestOption) (*DomainOverviewHistoryResponse, error)

LoadDomainOverviewHistory loads the historical index series for an unexpired overview snapshot. The request can spend provider budget and requires an explicit maximum cost, including zero for a cache-only attempt.

func (*Client) LoadDomainOverviewKeywords added in v0.8.0 

func (c *Client) LoadDomainOverviewKeywords(ctx context.Context, projectID string, input LoadDomainOverviewKeywordsOptions, options ...RequestOption) (*DomainOverviewKeywordsResponse, error)

LoadDomainOverviewKeywords loads one ranked-keyword page for a domain overview. The request can spend provider budget and requires an explicit maximum cost, including zero for a cache-only attempt.

func (*Client) LoadDomainOverviewPages added in v0.8.0 

func (c *Client) LoadDomainOverviewPages(ctx context.Context, projectID string, input LoadDomainOverviewPagesOptions, options ...RequestOption) (*DomainOverviewPagesResponse, error)

LoadDomainOverviewPages loads one relevant-page page for a domain overview. The request can spend provider budget and requires an explicit maximum cost, including zero for a cache-only attempt.

func (*Client) LoadMoreBacklinkRows added in v0.4.0 

func (c *Client) LoadMoreBacklinkRows(ctx context.Context, projectID string, input LoadMoreBacklinkRowsOptions, options ...RequestOption) (*BacklinksSnapshotResponse, error)

LoadMoreBacklinkRows loads paid rows into an unexpired backlinks snapshot. The endpoint requires write scope because the provider call spends project budget.

func (*Client) MarkProjectAlertsRead 

func (c *Client) MarkProjectAlertsRead(ctx context.Context, projectID string, options ...RequestOption) (*TriggeredAlertsReadResult, error)

MarkProjectAlertsRead marks every firing alert in a project as read.

func (*Client) MatchProjectKeywords added in v0.4.0 

func (c *Client) MatchProjectKeywords(ctx context.Context, projectID string, input KeywordMatchRequest, options ...RequestOption) (*KeywordMatchResponse, error)

MatchProjectKeywords matches exact tracked keyword texts across project markets.

func (*Client) MintMigrationToken 

func (c *Client) MintMigrationToken(ctx context.Context, projectID string, input MintMigrationTokenInput, options ...RequestOption) (*IssuedMigrationToken, error)

MintMigrationToken mints a migration token for a project.

func (*Client) MuteTriggeredAlert 

func (c *Client) MuteTriggeredAlert(ctx context.Context, projectID, alertID string, options ...RequestOption) (*TriggeredAlertMuteResult, error)

MuteTriggeredAlert mutes one triggered alert for 24 hours.

func (*Client) Projects 

func (c *Client) Projects(ctx context.Context, options ...RequestOption) (*ListResponse[Project], error)

Projects is an operation-style alias for ListProjects.

func (*Client) RankHistory 

func (c *Client) RankHistory(ctx context.Context, keywordID string, filters *ListRankChecksOptions, options ...RequestOption) (*ListResponse[RankCheck], error)

RankHistory is an operation-style alias for ListRankChecks.

func (*Client) RemoveCompetitor 

func (c *Client) RemoveCompetitor(ctx context.Context, competitorID string, options ...RequestOption) (*CompetitorRemoveResult, error)

RemoveCompetitor removes a competitor by ID using the top-level route.

func (*Client) RemoveProjectCompetitor 

func (c *Client) RemoveProjectCompetitor(ctx context.Context, projectID, competitorID string, options ...RequestOption) (*CompetitorRemoveResult, error)

RemoveProjectCompetitor removes a competitor by project and competitor ID.

func (*Client) RemoveTeamMember 

func (c *Client) RemoveTeamMember(ctx context.Context, projectID, memberID string, options ...RequestOption) (*TeamMemberMutationResult, error)

RemoveTeamMember permanently removes a non-owner project member.

func (*Client) ResearchKeywords 

func (c *Client) ResearchKeywords(ctx context.Context, projectID string, input ResearchKeywordsOptions, options ...RequestOption) (*KeywordResearchResponse, error)

ResearchKeywords researches related keywords, suggestions, and ideas from one seed. The endpoint requires an API key with write scope because cache misses can spend provider budget.

func (*Client) ResendTeamInvite 

func (c *Client) ResendTeamInvite(ctx context.Context, projectID, inviteID string, options ...RequestOption) (*TeamInviteResendResult, error)

ResendTeamInvite resends a pending project invite with a new token and expiration.

func (*Client) RevokeAPIKey 

func (c *Client) RevokeAPIKey(ctx context.Context, keyID string, options ...RequestOption) (*APIKey, error)

RevokeAPIKey revokes one API key.

func (*Client) RevokeMigrationToken 

func (c *Client) RevokeMigrationToken(ctx context.Context, tokenID string, options ...RequestOption) (*RevokedMigrationToken, error)

RevokeMigrationToken revokes a migration token by ID using the top-level route.

func (*Client) RevokeMyToken 

func (c *Client) RevokeMyToken(ctx context.Context, tokenID string, options ...RequestOption) (*PersonalAccessToken, error)

RevokeMyToken revokes one personal access token and returns the revoked resource. Revoking by ID requires admin tier; pass "current" to revoke the token used for the request, which works at any tier.

func (*Client) RevokeProjectMigrationToken 

func (c *Client) RevokeProjectMigrationToken(ctx context.Context, projectID, tokenID string, options ...RequestOption) (*RevokedMigrationToken, error)

RevokeProjectMigrationToken revokes a migration token by project and token ID.

func (*Client) RevokeProjectTeamInvite 

func (c *Client) RevokeProjectTeamInvite(ctx context.Context, projectID, inviteID string, options ...RequestOption) (*RevokeTeamInviteResult, error)

RevokeProjectTeamInvite revokes a team invite by project and invite ID.

func (*Client) RevokeTeamInvite 

func (c *Client) RevokeTeamInvite(ctx context.Context, inviteID string, options ...RequestOption) (*RevokeTeamInviteResult, error)

RevokeTeamInvite revokes a team invite by ID using the top-level route.

func (*Client) RunCheck 

func (c *Client) RunCheck(ctx context.Context, keywordID string, input *RunRankCheckInput, options ...RequestOption) (*RankCheck, error)

RunCheck is an operation-style alias for RunRankCheck.

func (*Client) RunRankCheck 

func (c *Client) RunRankCheck(ctx context.Context, keywordID string, input *RunRankCheckInput, options ...RequestOption) (*RankCheck, error)

RunRankCheck runs an immediate rank check for one keyword. When input.Async is true the check is enqueued with ?async=true and the API responds 202 with a RankCheck in status running.

func (*Client) SearchLocations 

func (c *Client) SearchLocations(ctx context.Context, input SearchLocationsOptions, options ...RequestOption) (*LocationSuggestionsResponse, error)

SearchLocations searches canonical location keys accepted by keyword methods.

func (*Client) SetKeywordTargetURL 

func (c *Client) SetKeywordTargetURL(ctx context.Context, keywordID string, targetURL *string, options ...RequestOption) (*Keyword, error)

SetKeywordTargetURL sets or clears a keyword target URL. Pass nil to clear it.

func (*Client) SetPrimaryProvider 

func (c *Client) SetPrimaryProvider(ctx context.Context, projectID string, providerID ProviderID, primary bool, options ...RequestOption) (*ProviderConnection, error)

SetPrimaryProvider marks or unmarks a provider as primary.

func (*Client) SetProviderEnabled 

func (c *Client) SetProviderEnabled(ctx context.Context, projectID string, providerID ProviderID, enabled bool, options ...RequestOption) (*ProviderConnection, error)

SetProviderEnabled enables or disables a provider connection.

func (*Client) SetProviderPriority 

func (c *Client) SetProviderPriority(ctx context.Context, projectID string, providerID ProviderID, priority int, options ...RequestOption) (*ProviderConnection, error)

SetProviderPriority sets a provider fallback priority.

func (*Client) SyncProjectTraffic 

func (c *Client) SyncProjectTraffic(ctx context.Context, projectID string, options ...RequestOption) (*TrafficSyncSummary, error)

SyncProjectTraffic runs the project's analytics traffic synchronization now. Pass WithIdempotencyKey to satisfy the endpoint's idempotency requirement.

func (*Client) TestProviderConnection 

func (c *Client) TestProviderConnection(ctx context.Context, projectID string, providerID ProviderID, input TestProviderConnectionInput, options ...RequestOption) (*ProviderTestResult, error)

TestProviderConnection tests credentials or a stored connection for a project provider.

func (*Client) UpdateAlertRule 

func (c *Client) UpdateAlertRule(ctx context.Context, ruleID string, input UpdateAlertRuleInput, options ...RequestOption) (*AlertRule, error)

UpdateAlertRule updates an alert rule by ID.

func (*Client) UpdateKeyword 

func (c *Client) UpdateKeyword(ctx context.Context, keywordID string, input UpdateKeywordInput, options ...RequestOption) (*Keyword, error)

UpdateKeyword patches keyword metadata.

func (*Client) UpdateMe 

func (c *Client) UpdateMe(ctx context.Context, input UpdateMeInput, options ...RequestOption) (*Me, error)

UpdateMe patches the authenticated user's profile. Requires a personal access token with write tier.

func (*Client) UpdateNotificationPreferences 

func (c *Client) UpdateNotificationPreferences(ctx context.Context, projectID string, input UpdateNotificationPreferencesInput, options ...RequestOption) (*UpdatedNotificationPreferences, error)

UpdateNotificationPreferences patches project notification preferences for the current user.

func (*Client) UpdateProject 

func (c *Client) UpdateProject(ctx context.Context, projectID string, input UpdateProjectInput, options ...RequestOption) (*Project, error)

UpdateProject patches project name or domain. At least one input field is required.

func (*Client) UpdateProjectDefaults 

func (c *Client) UpdateProjectDefaults(ctx context.Context, projectID string, input ProjectDefaultsPatch, options ...RequestOption) (*ProjectDefaults, error)

UpdateProjectDefaults patches project default market and schedule settings.

func (*Client) UpdateProviderSettings 

func (c *Client) UpdateProviderSettings(ctx context.Context, projectID string, providerID ProviderID, input ProviderSettingsInput, options ...RequestOption) (*ProviderConnection, error)

UpdateProviderSettings updates enabled, primary, or priority settings for a provider.

func (*Client) UpdateSitemapMonitor 

func (c *Client) UpdateSitemapMonitor(ctx context.Context, projectID, monitorID string, input UpdateSitemapMonitorInput, options ...RequestOption) (*SitemapMonitor, error)

UpdateSitemapMonitor enables or disables a project sitemap monitor.

func (*Client) UpdateTeamMemberRole 

func (c *Client) UpdateTeamMemberRole(ctx context.Context, projectID, memberID string, input UpdateTeamMemberRoleInput, options ...RequestOption) (*TeamMemberRoleResult, error)

UpdateTeamMemberRole changes a non-owner project member's role.

func (*Client) UpdateWebhook 

func (c *Client) UpdateWebhook(ctx context.Context, projectID, webhookID string, input UpdateWebhookInput, options ...RequestOption) (*Webhook, error)

UpdateWebhook patches a webhook by project and webhook ID.

func (*Client) UploadCloudImportChunk 

func (c *Client) UploadCloudImportChunk(ctx context.Context, migrationToken, sessionID string, index int, chunk CloudImportUploadChunk, options ...RequestOption) (*CloudImportChunkResponse, error)

UploadCloudImportChunk uploads one JSON chunk to a chunked import session, authenticated with a migration token. index is the zero-based chunk position. The chunk is sent as an application/json body.

func (*Client) UploadCloudImportChunkRaw 

func (c *Client) UploadCloudImportChunkRaw(ctx context.Context, migrationToken, sessionID string, index int, body io.Reader, gzip bool, options ...RequestOption) (*CloudImportChunkResponse, error)

UploadCloudImportChunkRaw uploads one pre-serialized JSON chunk body to a chunked import session. Use it to stream a chunk from an io.Reader or to send a gzip-compressed body: pass the raw application/json bytes as body, and set gzip to true when body is gzip compressed so the server receives the Content-Encoding: gzip header. The body must still decode to a CloudImportUploadChunk.

type CloudImportAlertCondition added in v0.5.0 

type CloudImportAlertCondition string

CloudImportAlertCondition identifies a migrated alert-rule condition. 

const (
	CloudImportAlertConditionChangePct          CloudImportAlertCondition = "change_pct"
	CloudImportAlertConditionCompetitorOvertake CloudImportAlertCondition = "competitor_overtake"
	CloudImportAlertConditionCTRDrop            CloudImportAlertCondition = "ctr_drop"
	CloudImportAlertConditionDowntrend          CloudImportAlertCondition = "downtrend"
	CloudImportAlertConditionEntersTopN         CloudImportAlertCondition = "enters_top_n"
	CloudImportAlertConditionExitsTopN          CloudImportAlertCondition = "exits_top_n"
	CloudImportAlertConditionPositionDrop       CloudImportAlertCondition = "position_drop"
	CloudImportAlertConditionSERPFeature        CloudImportAlertCondition = "serp_feature"
	CloudImportAlertConditionThreshold          CloudImportAlertCondition = "threshold"
	CloudImportAlertConditionURLMismatch        CloudImportAlertCondition = "url_mismatch"
)

type CloudImportAlertRule 

type CloudImportAlertRule struct {
	ChangePct         *float64                     `json:"change_pct,omitempty"`
	Channels          []AlertChannel               `json:"channels,omitempty"`
	CompetitorDomain  *string                      `json:"competitor_domain,omitempty"`
	ConditionType     CloudImportAlertCondition    `json:"condition_type,omitempty"`
	DropPositions     *int                         `json:"drop_positions,omitempty"`
	Enabled           *bool                        `json:"enabled,omitempty"`
	ID                string                       `json:"id"`
	Name              string                       `json:"name"`
	SerpFeature       *string                      `json:"serp_feature,omitempty"`
	TargetType        AlertTargetType              `json:"target_type,omitempty"`
	Targets           []CloudImportAlertRuleTarget `json:"targets,omitempty"`
	ThresholdPosition *int                         `json:"threshold_position,omitempty"`
	TopN              *int                         `json:"top_n,omitempty"`
}

CloudImportAlertRule is a migrated alert rule. ID and Name are required.

func (CloudImportAlertRule) MarshalJSON added in v0.5.0 

func (input CloudImportAlertRule) MarshalJSON() ([]byte, error)

func (*CloudImportAlertRule) UnmarshalJSON added in v0.5.0 

func (input *CloudImportAlertRule) UnmarshalJSON(data []byte) error

type CloudImportAlertRuleTarget 

type CloudImportAlertRuleTarget interface {
	// contains filtered or unexported methods
}

CloudImportAlertRuleTarget is a sealed discriminated union. Use either CloudImportKeywordAlertTarget or CloudImportTagAlertTarget.

type CloudImportChunkLimits 

type CloudImportChunkLimits struct {
	MaxBodyBytes   int `json:"max_body_bytes"`
	MaxHistoryRows int `json:"max_history_rows"`
	MaxKeywords    int `json:"max_keywords"`
}

CloudImportChunkLimits reports the per-chunk limits enforced by the server.

func (CloudImportChunkLimits) MarshalJSON added in v0.5.0 

func (input CloudImportChunkLimits) MarshalJSON() ([]byte, error)

func (*CloudImportChunkLimits) UnmarshalJSON added in v0.5.0 

func (input *CloudImportChunkLimits) UnmarshalJSON(data []byte) error

type CloudImportChunkResponse 

type CloudImportChunkResponse struct {
	ChunkCount     int              `json:"chunk_count"`
	ChunksReceived int              `json:"chunks_received"`
	State          CloudImportState `json:"state"`
}

CloudImportChunkResponse is returned when a chunk is accepted.

func (CloudImportChunkResponse) MarshalJSON added in v0.5.0 

func (input CloudImportChunkResponse) MarshalJSON() ([]byte, error)

func (*CloudImportChunkResponse) UnmarshalJSON added in v0.5.0 

func (input *CloudImportChunkResponse) UnmarshalJSON(data []byte) error

type CloudImportCompatibility 

type CloudImportCompatibility struct {
	AppVersion              string  `json:"app_version"`
	LatestMigration         *string `json:"latest_migration"`
	SchemaVersionsSupported []int   `json:"schema_versions_supported"`
}

CloudImportCompatibility is the unauthenticated schema-compatibility preflight. A valid response lists only protocol version 5.

func (CloudImportCompatibility) MarshalJSON added in v0.5.0 

func (input CloudImportCompatibility) MarshalJSON() ([]byte, error)

func (*CloudImportCompatibility) UnmarshalJSON added in v0.5.0 

func (input *CloudImportCompatibility) UnmarshalJSON(data []byte) error

type CloudImportCompetitor 

type CloudImportCompetitor struct {
	Domain string  `json:"domain"`
	ID     string  `json:"id"`
	Label  *string `json:"label,omitempty"`
}

CloudImportCompetitor is a migrated managed competitor. ID and Domain are required.

func (CloudImportCompetitor) MarshalJSON added in v0.5.0 

func (input CloudImportCompetitor) MarshalJSON() ([]byte, error)

func (*CloudImportCompetitor) UnmarshalJSON added in v0.5.0 

func (input *CloudImportCompetitor) UnmarshalJSON(data []byte) error

type CloudImportCounts 

type CloudImportCounts map[string]int

CloudImportCounts maps an imported resource name to the number of records created for it.

type CloudImportFinalizeResponse 

type CloudImportFinalizeResponse struct {
	Counts CloudImportCounts `json:"counts"`
	JobID  string            `json:"job_id"`
	State  CloudImportState  `json:"state"`
}

CloudImportFinalizeResponse is returned after a completed import. JobID is always a strict imp_ public ID and State is always done.

func (CloudImportFinalizeResponse) MarshalJSON added in v0.5.0 

func (input CloudImportFinalizeResponse) MarshalJSON() ([]byte, error)

func (*CloudImportFinalizeResponse) UnmarshalJSON added in v0.5.0 

func (input *CloudImportFinalizeResponse) UnmarshalJSON(data []byte) error

type CloudImportJob 

type CloudImportJob struct {
	Counts     json.RawMessage  `json:"counts"`
	CreatedAt  *time.Time       `json:"created_at"`
	Error      *string          `json:"error"`
	FinishedAt *time.Time       `json:"finished_at"`
	ID         *string          `json:"id"`
	Progress   int              `json:"progress"`
	StartedAt  *time.Time       `json:"started_at"`
	State      CloudImportState `json:"state"`
}

CloudImportJob describes migration import job status.

type CloudImportKeyword 

type CloudImportKeyword struct {
	Device         Device                      `json:"device"`
	ID             string                      `json:"id"`
	Keyword        string                      `json:"keyword"`
	Location       string                      `json:"location"`
	RankingHistory []CloudImportRankingHistory `json:"rankingHistory,omitempty"`
	Tags           []string                    `json:"tags,omitempty"`
	TargetURL      *string                     `json:"target_url,omitempty"`
}

CloudImportKeyword is a migrated keyword. ID, Keyword, Device, and Location are required. rankingHistory deliberately remains camelCase because that is the v5 OpenAPI wire contract.

func (CloudImportKeyword) MarshalJSON added in v0.5.0 

func (input CloudImportKeyword) MarshalJSON() ([]byte, error)

func (*CloudImportKeyword) UnmarshalJSON added in v0.5.0 

func (input *CloudImportKeyword) UnmarshalJSON(data []byte) error

type CloudImportKeywordAlertTarget added in v0.5.0 

type CloudImportKeywordAlertTarget struct {
	Device    Device `json:"device,omitempty"`
	Keyword   string `json:"keyword,omitempty"`
	KeywordID string `json:"keyword_id"`
	Location  string `json:"location,omitempty"`
}

CloudImportKeywordAlertTarget is the keyword variant of an alert-rule target. Its JSON representation always includes type: "keyword".

func (CloudImportKeywordAlertTarget) MarshalJSON added in v0.5.0 

func (input CloudImportKeywordAlertTarget) MarshalJSON() ([]byte, error)

func (*CloudImportKeywordAlertTarget) UnmarshalJSON added in v0.5.0 

func (input *CloudImportKeywordAlertTarget) UnmarshalJSON(data []byte) error

type CloudImportKeywordsChunk added in v0.5.0 

type CloudImportKeywordsChunk struct {
	Checksum string               `json:"checksum"`
	Keywords []CloudImportKeyword `json:"keywords"`
}

CloudImportKeywordsChunk uploads a required keywords array. Its JSON representation always includes kind: "keywords".

func (CloudImportKeywordsChunk) MarshalJSON added in v0.5.0 

func (input CloudImportKeywordsChunk) MarshalJSON() ([]byte, error)

func (*CloudImportKeywordsChunk) UnmarshalJSON added in v0.5.0 

func (input *CloudImportKeywordsChunk) UnmarshalJSON(data []byte) error

type CloudImportNotificationPreference 

type CloudImportNotificationPreference struct {
	AlertEmail  *bool `json:"alert_email,omitempty"`
	AlertInApp  *bool `json:"alert_in_app,omitempty"`
	CheckEmail  *bool `json:"check_email,omitempty"`
	CheckInApp  *bool `json:"check_in_app,omitempty"`
	ImportEmail *bool `json:"import_email,omitempty"`
	ImportInApp *bool `json:"import_in_app,omitempty"`
	InviteEmail *bool `json:"invite_email,omitempty"`
	InviteInApp *bool `json:"invite_in_app,omitempty"`
	ReportEmail *bool `json:"report_email,omitempty"`
}

CloudImportNotificationPreference is one migrated per-user notification preference set.

func (CloudImportNotificationPreference) MarshalJSON added in v0.5.0 

func (input CloudImportNotificationPreference) MarshalJSON() ([]byte, error)

func (*CloudImportNotificationPreference) UnmarshalJSON added in v0.5.0 

func (input *CloudImportNotificationPreference) UnmarshalJSON(data []byte) error

type CloudImportPackage 

type CloudImportPackage struct {
	AlertRules              []CloudImportAlertRule              `json:"alert_rules"`
	Competitors             []CloudImportCompetitor             `json:"competitors"`
	ExportedAt              *time.Time                          `json:"exported_at,omitempty"`
	Keywords                []CloudImportKeyword                `json:"keywords"`
	NotificationPreferences []CloudImportNotificationPreference `json:"notification_preferences"`
	ProjectID               string                              `json:"project_id"`
	SavedViews              []CloudImportSavedView              `json:"saved_views"`
	Scope                   CloudImportScope                    `json:"scope,omitempty"`
}

CloudImportPackage is the complete v5 export accepted by ImportCloudExport. The SDK writes version 5 itself. Every collection below is required and must be represented by a non-nil slice, including when it is empty.

func (CloudImportPackage) MarshalJSON added in v0.5.0 

func (input CloudImportPackage) MarshalJSON() ([]byte, error)

func (*CloudImportPackage) UnmarshalJSON added in v0.5.0 

func (input *CloudImportPackage) UnmarshalJSON(data []byte) error

type CloudImportRankingHistory 

type CloudImportRankingHistory struct {
	CheckedAt        time.Time `json:"checkedAt"`
	Position         *int      `json:"position,omitempty"`
	PreviousPosition *int      `json:"previousPosition,omitempty"`
	RankingURL       *string   `json:"rankingUrl,omitempty"`
}

CloudImportRankingHistory is one migrated ranking-history point. CheckedAt is required and uses the API's camelCase nested wire property.

func (CloudImportRankingHistory) MarshalJSON added in v0.5.0 

func (input CloudImportRankingHistory) MarshalJSON() ([]byte, error)

func (*CloudImportRankingHistory) UnmarshalJSON added in v0.5.0 

func (input *CloudImportRankingHistory) UnmarshalJSON(data []byte) error

type CloudImportSavedView 

type CloudImportSavedView struct {
	Config  any                         `json:"config,omitempty"`
	ID      string                      `json:"id"`
	Name    string                      `json:"name"`
	Surface CloudImportSavedViewSurface `json:"surface,omitempty"`
}

CloudImportSavedView is a migrated saved view. Config is intentionally an unconstrained JSON value, matching the OpenAPI schema.

func (CloudImportSavedView) MarshalJSON added in v0.5.0 

func (input CloudImportSavedView) MarshalJSON() ([]byte, error)

func (*CloudImportSavedView) UnmarshalJSON added in v0.5.0 

func (input *CloudImportSavedView) UnmarshalJSON(data []byte) error

type CloudImportSavedViewSurface added in v0.5.0 

type CloudImportSavedViewSurface string

CloudImportSavedViewSurface identifies the saved-view surface. 

const (
	CloudImportSavedViewSurfaceKeywords    CloudImportSavedViewSurface = "keywords"
	CloudImportSavedViewSurfaceCompetitors CloudImportSavedViewSurface = "competitors"
)

type CloudImportScope added in v0.5.0 

type CloudImportScope string

CloudImportScope selects the data included in an export package. 

const (
	CloudImportScopeCurrent CloudImportScope = "current"
	CloudImportScopeHistory CloudImportScope = "history"
)

type CloudImportSectionsChunk added in v0.5.0 

type CloudImportSectionsChunk struct {
	Checksum string                     `json:"checksum"`
	Sections CloudImportSessionSections `json:"sections"`
}

CloudImportSectionsChunk uploads a required sections object. Its JSON representation always includes kind: "sections".

func (CloudImportSectionsChunk) MarshalJSON added in v0.5.0 

func (input CloudImportSectionsChunk) MarshalJSON() ([]byte, error)

func (*CloudImportSectionsChunk) UnmarshalJSON added in v0.5.0 

func (input *CloudImportSectionsChunk) UnmarshalJSON(data []byte) error

type CloudImportSessionCreate 

type CloudImportSessionCreate struct {
	ChunkCount      int                       `json:"chunk_count"`
	SourceProjectID string                    `json:"source_project_id"`
	Totals          *CloudImportSessionTotals `json:"totals,omitempty"`
}

CloudImportSessionCreate creates a chunked v5 cloud-import session. The SDK writes version 5 itself; ChunkCount and SourceProjectID are required.

func (CloudImportSessionCreate) MarshalJSON added in v0.5.0 

func (input CloudImportSessionCreate) MarshalJSON() ([]byte, error)

func (*CloudImportSessionCreate) UnmarshalJSON added in v0.5.0 

func (input *CloudImportSessionCreate) UnmarshalJSON(data []byte) error

type CloudImportSessionCreateResponse 

type CloudImportSessionCreateResponse struct {
	ChunkLimits CloudImportChunkLimits `json:"chunk_limits"`
	SessionID   string                 `json:"session_id"`
	State       CloudImportState       `json:"state"`
}

CloudImportSessionCreateResponse is returned by CreateCloudImportSession. SessionID is an imp_ public ID despite the route retaining "sessions".

func (CloudImportSessionCreateResponse) MarshalJSON added in v0.5.0 

func (input CloudImportSessionCreateResponse) MarshalJSON() ([]byte, error)

func (*CloudImportSessionCreateResponse) UnmarshalJSON added in v0.5.0 

func (input *CloudImportSessionCreateResponse) UnmarshalJSON(data []byte) error

type CloudImportSessionSections 

type CloudImportSessionSections struct {
	AlertRules              []CloudImportAlertRule              `json:"alert_rules,omitempty"`
	Competitors             []CloudImportCompetitor             `json:"competitors,omitempty"`
	NotificationPreferences []CloudImportNotificationPreference `json:"notification_preferences,omitempty"`
	SavedViews              []CloudImportSavedView              `json:"saved_views,omitempty"`
	SourceKeywordIDs        map[string]CloudImportSourceKeyword `json:"source_keyword_ids,omitempty"`
}

CloudImportSessionSections carries the non-keyword sections in a sections chunk. All section properties are optional, as specified by v5.

func (CloudImportSessionSections) MarshalJSON added in v0.5.0 

func (input CloudImportSessionSections) MarshalJSON() ([]byte, error)

func (*CloudImportSessionSections) UnmarshalJSON added in v0.5.0 

func (input *CloudImportSessionSections) UnmarshalJSON(data []byte) error

type CloudImportSessionTotals 

type CloudImportSessionTotals struct {
	Keywords   int `json:"keywords"`
	RankChecks int `json:"rank_checks"`
}

CloudImportSessionTotals declares optional expected record totals for a chunked import session.

func (CloudImportSessionTotals) MarshalJSON added in v0.5.0 

func (input CloudImportSessionTotals) MarshalJSON() ([]byte, error)

func (*CloudImportSessionTotals) UnmarshalJSON added in v0.5.0 

func (input *CloudImportSessionTotals) UnmarshalJSON(data []byte) error

type CloudImportSourceKeyword 

type CloudImportSourceKeyword struct {
	Device   Device `json:"device"`
	Location string `json:"location"`
	Text     string `json:"text"`
}

CloudImportSourceKeyword identifies a source keyword in a sections chunk.

func (CloudImportSourceKeyword) MarshalJSON added in v0.5.0 

func (input CloudImportSourceKeyword) MarshalJSON() ([]byte, error)

func (*CloudImportSourceKeyword) UnmarshalJSON added in v0.5.0 

func (input *CloudImportSourceKeyword) UnmarshalJSON(data []byte) error

type CloudImportState 

type CloudImportState string

CloudImportState is the current state of a migration import job. 

const (
	CloudImportStateIdle      CloudImportState = "idle"
	CloudImportStateReceiving CloudImportState = "receiving"
	CloudImportStateImporting CloudImportState = "importing"
	CloudImportStateDone      CloudImportState = "done"
	CloudImportStateFailed    CloudImportState = "failed"
)

type CloudImportTagAlertTarget added in v0.5.0 

type CloudImportTagAlertTarget struct {
	Tag string `json:"tag"`
}

CloudImportTagAlertTarget is the tag variant of an alert-rule target. Its JSON representation always includes type: "tag".

func (CloudImportTagAlertTarget) MarshalJSON added in v0.5.0 

func (input CloudImportTagAlertTarget) MarshalJSON() ([]byte, error)

func (*CloudImportTagAlertTarget) UnmarshalJSON added in v0.5.0 

func (input *CloudImportTagAlertTarget) UnmarshalJSON(data []byte) error

type CloudImportUploadChunk 

type CloudImportUploadChunk interface {
	// contains filtered or unexported methods
}

CloudImportUploadChunk is a sealed discriminated union. Use either CloudImportKeywordsChunk or CloudImportSectionsChunk.

type Competitor 

type Competitor struct {
	Domain string  `json:"domain"`
	ID     string  `json:"id"`
	Label  *string `json:"label"`
}

Competitor is returned by competitor write endpoints.

type CompetitorColumn 

type CompetitorColumn struct {
	Domain string `json:"domain"`
	ID     string `json:"id,omitempty"`
	Kind   string `json:"kind"`
	Label  string `json:"label"`
}

CompetitorColumn is one column in a competitor market response.

type CompetitorHeadToHeadRow 

type CompetitorHeadToHeadRow struct {
	Gap     *int            `json:"gap"`
	Keyword string          `json:"keyword"`
	Ranks   map[string]*int `json:"ranks"`
}

CompetitorHeadToHeadRow is one keyword row in a competitor market response.

type CompetitorMarket 

type CompetitorMarket struct {
	CheckedKeywordCount int                       `json:"checked_keyword_count"`
	Columns             []CompetitorColumn        `json:"columns"`
	CompetitorCount     int                       `json:"competitor_count"`
	Country             string                    `json:"country"`
	Device              string                    `json:"device"`
	Engine              string                    `json:"engine"`
	HasRankData         bool                      `json:"has_rank_data"`
	Key                 string                    `json:"key"`
	Rows                []CompetitorHeadToHeadRow `json:"rows"`
	Shares              []CompetitorShare         `json:"shares"`
	SharedKeywordCount  int                       `json:"shared_keyword_count"`
	TrackedKeywordCount int                       `json:"tracked_keyword_count"`
}

CompetitorMarket summarizes competitors for one country, device, and engine.

type CompetitorRemoveResult 

type CompetitorRemoveResult struct {
	Removed bool `json:"removed"`
}

CompetitorRemoveResult is returned after removing a competitor.

type CompetitorShare 

type CompetitorShare struct {
	Color          string `json:"color"`
	Domain         string `json:"domain"`
	ID             string `json:"id,omitempty"`
	Initials       string `json:"initials"`
	Kind           string `json:"kind"`
	Label          string `json:"label"`
	ShareOfVoice   int    `json:"share_of_voice"`
	SharedKeywords int    `json:"shared_keywords"`
}

CompetitorShare is one share-of-voice entry in a competitor market response.

type CompetitorsMeta 

type CompetitorsMeta struct {
	NextCursor  *string               `json:"next_cursor"`
	Markets     []CompetitorMarket    `json:"markets"`
	Suggestions []SuggestedCompetitor `json:"suggestions"`
}

CompetitorsMeta contains list pagination plus competitor market metadata.

type ConfigurationError 

type ConfigurationError struct {
	Message string
}

ConfigurationError reports invalid client configuration or missing credentials.

func (*ConfigurationError) Error 

func (e *ConfigurationError) Error() string

type ConnectProviderInput 

type ConnectProviderInput struct {
	CostPerCheck *float64                  `json:"cost_per_check,omitempty"`
	Credentials  *ProviderCredentialsInput `json:"credentials,omitempty"`
	Enabled      *bool                     `json:"enabled,omitempty"`
	Login        string                    `json:"login,omitempty"`
	Primary      *bool                     `json:"primary,omitempty"`
	Priority     *int                      `json:"priority,omitempty"`
	Secret       string                    `json:"secret,omitempty"`
}

ConnectProviderInput connects or updates provider credentials for a project.

type CostEstimate 

type CostEstimate struct {
	ChecksPerRun               int                 `json:"checks_per_run"`
	EffectiveCostPerCheckCents float64             `json:"effective_cost_per_check_cents"`
	ExceedsLargestPlan         bool                `json:"exceeds_largest_plan"`
	ExceedsSelectedPlan        bool                `json:"exceeds_selected_plan"`
	MonthlyChecks              int                 `json:"monthly_checks"`
	MonthlyCostCents           float64             `json:"monthly_cost_cents"`
	MonthlyCostUSD             float64             `json:"monthly_cost_usd"`
	PricingModel               PricingModel        `json:"pricing_model"`
	ProviderID                 ProviderID          `json:"provider_id"`
	RateCheckedAt              string              `json:"rate_checked_at"`
	RateSourceURL              string              `json:"rate_source_url"`
	SelectedOption             *ProviderRateOption `json:"selected_option,omitempty"`
	SelectedPlan               *ProviderRatePlan   `json:"selected_plan,omitempty"`
}

CostEstimate is a public monthly cost estimate for one provider rate card.

type CostEstimateOptions 

type CostEstimateOptions struct {
	Keywords  int
	Devices   int
	Frequency EstimateFrequency
	Locations int
	Option    string
	Plan      string
	Provider  ProviderID
}

CostEstimateOptions are the query parameters accepted by GetCostEstimate. Keywords is required (0 is valid) and capped at 100000. Locations is capped at 100 and Devices at 2; both default to 1. Frequency defaults to daily and Provider defaults to dataforseo. Option pins a flat-rate option key and Plan pins a plan key; both are optional.

type CreateAPIKeyInput 

type CreateAPIKeyInput struct {
	Name string `json:"name"`
}

CreateAPIKeyInput creates an API key.

type CreateAlertRuleInput 

type CreateAlertRuleInput struct {
	Channels          []AlertChannel     `json:"channels,omitempty"`
	ChangePct         *float64           `json:"change_pct,omitempty"`
	CompetitorDomain  *string            `json:"competitor_domain,omitempty"`
	ConditionType     AlertConditionType `json:"condition_type"`
	Enabled           *bool              `json:"enabled,omitempty"`
	Name              string             `json:"name"`
	RecipientIDs      []string           `json:"recipient_ids,omitempty"`
	SERPFeature       *string            `json:"serp_feature,omitempty"`
	TargetIDs         []string           `json:"target_ids,omitempty"`
	TargetType        AlertTargetType    `json:"target_type,omitempty"`
	ThresholdPosition *int               `json:"threshold_position,omitempty"`
	TopN              *int               `json:"top_n,omitempty"`
}

CreateAlertRuleInput creates an alert rule for a project.

type CreateKeywordInput 

type CreateKeywordInput struct {
	Keyword     string                `json:"keyword"`
	City        string                `json:"city,omitempty"`
	Country     string                `json:"country,omitempty"`
	Location    string                `json:"location,omitempty"`
	LocationKey string                `json:"location_key,omitempty"`
	Device      Device                `json:"device,omitempty"`
	Intent      *string               `json:"intent,omitempty"`
	Topic       *string               `json:"topic,omitempty"`
	Schedule    *KeywordScheduleInput `json:"schedule,omitempty"`
	Tags        []string              `json:"tags,omitempty"`
	TargetURL   *string               `json:"target_url,omitempty"`
}

CreateKeywordInput is one keyword item accepted by CreateKeywords and AddKeywords. LocationKey accepts canonical country, region, or city keys, optionally qualified with @language.

type CreateKeywordResult 

type CreateKeywordResult struct {
	Keyword Keyword `json:"keyword"`
	Status  string  `json:"status"`
	Warning string  `json:"warning,omitempty"`
}

CreateKeywordResult describes one create result.

type CreateKeywordsInput 

type CreateKeywordsInput struct {
	Keywords []CreateKeywordInput `json:"keywords"`
}

CreateKeywordsInput wraps one or more keyword creation items.

type CreateKeywordsResponse 

type CreateKeywordsResponse struct {
	Created  int                   `json:"created"`
	Skipped  int                   `json:"skipped"`
	Results  []CreateKeywordResult `json:"results"`
	Warnings []string              `json:"warnings,omitempty"`
}

CreateKeywordsResponse summarizes a keyword creation request.

type CreateMyTokenInput 

type CreateMyTokenInput struct {
	ExpiresInDays *int       `json:"expires_in_days,omitempty"`
	Name          string     `json:"name"`
	Scope         TokenScope `json:"scope,omitempty"`
}

CreateMyTokenInput mints a personal access token. Scope defaults to TokenScopeRead when omitted. ExpiresInDays accepts 30, 90, or 365; leave it nil for a token that never expires.

type CreateProjectInput 

type CreateProjectInput struct {
	Defaults      *ProjectDefaultsPatch `json:"defaults,omitempty"`
	Domain        string                `json:"domain"`
	Name          string                `json:"name"`
	TrackingScope TrackingScope         `json:"tracking_scope,omitempty"`
}

CreateProjectInput creates a project. TrackingScope defaults to TrackingScopeCountry and Defaults falls back to server defaults when omitted.

type CreateSavedKeywordsInput added in v0.6.0 

type CreateSavedKeywordsInput struct {
	Keywords []SavedKeywordItem `json:"keywords"`
}

CreateSavedKeywordsInput saves keywords for a project.

type CreateSavedKeywordsResult added in v0.6.0 

type CreateSavedKeywordsResult struct {
	DuplicateCount int                  `json:"duplicate_count"`
	Results        []SavedKeywordResult `json:"results"`
	SavedCount     int                  `json:"saved_count"`
}

CreateSavedKeywordsResult is returned by CreateSavedKeywords.

type CreateSavedViewInput 

type CreateSavedViewInput struct {
	Config SavedViewConfig `json:"config"`
	Name   string          `json:"name"`
}

CreateSavedViewInput creates a project saved view.

type CreateSignalInput 

type CreateSignalInput struct {
	HappenedAt *time.Time     `json:"happened_at,omitempty"`
	KeywordID  string         `json:"keyword_id,omitempty"`
	Payload    JSONValue      `json:"payload,omitempty"`
	Severity   SignalSeverity `json:"severity,omitempty"`
	Source     SignalSource   `json:"source"`
	Type       string         `json:"type"`
	URL        string         `json:"url,omitempty"`
}

CreateSignalInput ingests a signal for the API key's project. Source must be SignalSourceDeploy, SignalSourceCMS, or SignalSourceAPI. Type must match ^[a-z_]+\.[a-z_]+$ (for example deploy.completed). HappenedAt defaults to the ingestion time and Severity defaults to info when omitted. Payload must serialize to 8KB or less and URL must use http or https.

type CreateTeamInviteInput 

type CreateTeamInviteInput struct {
	Email string `json:"email"`
	// Role must be TeamRoleAdmin, TeamRoleMember, or TeamRoleViewer. The API
	// rejects TeamRoleOwner for invites; owner only appears in member
	// responses.
	Role TeamRoleValue `json:"role"`
}

CreateTeamInviteInput creates a project team invite.

type CreateWebhookInput 

type CreateWebhookInput struct {
	Description string `json:"description,omitempty"`
	Enabled     *bool  `json:"enabled,omitempty"`
	HMACSecret  string `json:"hmac_secret"`
	URL         string `json:"url"`
}

CreateWebhookInput creates a project webhook. HMACSecret must be at least 16 characters; it is write-only and never returned by the API.

type CreatedAPIKey 

type CreatedAPIKey struct {
	APIKey
	MaskedValue string `json:"masked_value"`
	Token       string `json:"token"`
}

CreatedAPIKey is returned once when creating an API key.

type CreatedPersonalAccessToken 

type CreatedPersonalAccessToken struct {
	PersonalAccessToken
	MaskedValue string `json:"masked_value"`
	Token       string `json:"token"`
}

CreatedPersonalAccessToken is returned once when minting a personal access token. Token carries the raw bsb_pat_live_ secret and is never shown again.

type CreatedTeamInvite 

type CreatedTeamInvite struct {
	ExpiresAt  time.Time `json:"expires_at"`
	ID         string    `json:"id"`
	InviteLink string    `json:"invite_link"`
}

CreatedTeamInvite is returned after creating a project team invite.

type DataResponse 

type DataResponse[T any] struct {
	Data T         `json:"data"`
	Meta JSONValue `json:"meta,omitempty"`
}

DataResponse is returned by endpoints that wrap data in a response envelope.

type Device 

type Device string

Device identifies the search device used for keyword rank tracking. 

const (
	DeviceDesktop Device = "desktop"
	DeviceMobile  Device = "mobile"
)

type DomainOverviewAnalyzeResponse added in v0.8.0 

type DomainOverviewAnalyzeResponse = DataResponse[DomainOverviewAnalyzeResult]

DomainOverviewAnalyzeResponse wraps an estimate or report in the public API data envelope.

type DomainOverviewAnalyzeResult added in v0.8.0 

type DomainOverviewAnalyzeResult struct {
	Estimate *DomainOverviewEstimate
	Report   *DomainOverviewReport
}

DomainOverviewAnalyzeResult is the discriminated estimate/report response data. Exactly one pointer is set after successful decoding.

func (*DomainOverviewAnalyzeResult) UnmarshalJSON added in v0.8.0 

func (result *DomainOverviewAnalyzeResult) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes an AnalyzeDomainOverview result using estimate=true as its discriminator.

type DomainOverviewEstimate added in v0.8.0 

type DomainOverviewEstimate struct {
	Cached                        bool                      `json:"cached"`
	Estimate                      bool                      `json:"estimate"`
	EstimatedCostCents            float64                   `json:"estimated_cost_cents"`
	FreshEstimatedCostCents       float64                   `json:"fresh_estimated_cost_cents"`
	HistoryEstimatedCostCents     float64                   `json:"history_estimated_cost_cents"`
	HistoryMode                   DomainOverviewHistoryMode `json:"history_mode"`
	KeywordPageEstimatedCostCents float64                   `json:"keyword_page_estimated_cost_cents"`
	LanguageCode                  string                    `json:"language_code"`
	LocationCode                  int                       `json:"location_code"`
	PagePageEstimatedCostCents    float64                   `json:"page_page_estimated_cost_cents"`
	Provider                      string                    `json:"provider"`
	Scope                         DomainOverviewScope       `json:"scope"`
	Target                        string                    `json:"target"`
}

DomainOverviewEstimate is the cache-aware estimate variant returned by AnalyzeDomainOverview.

type DomainOverviewFailureReason added in v0.8.0 

type DomainOverviewFailureReason string

DomainOverviewFailureReason is the machine-readable reason for a failed nested report module. 

const (
	DomainOverviewFailureBudgetExhausted     DomainOverviewFailureReason = "budget_exhausted"
	DomainOverviewFailureCostLimitExceeded   DomainOverviewFailureReason = "cost_limit_exceeded"
	DomainOverviewFailureInProgress          DomainOverviewFailureReason = "in_progress"
	DomainOverviewFailureLookupFailed        DomainOverviewFailureReason = "lookup_failed"
	DomainOverviewFailureNeedsReauth         DomainOverviewFailureReason = "needs_reauth"
	DomainOverviewFailureNoSource            DomainOverviewFailureReason = "no_source"
	DomainOverviewFailureRateLimited         DomainOverviewFailureReason = "rate_limited"
	DomainOverviewFailureSnapshotExpired     DomainOverviewFailureReason = "snapshot_expired"
	DomainOverviewFailureUnsupportedLocation DomainOverviewFailureReason = "unsupported_location"
)

type DomainOverviewHistoryMode added in v0.8.0 

type DomainOverviewHistoryMode string

DomainOverviewHistoryMode identifies how historical data is loaded. 

const DomainOverviewHistoryModeLazy DomainOverviewHistoryMode = "lazy"

type DomainOverviewHistoryResponse added in v0.8.0 

type DomainOverviewHistoryResponse = DataResponse[DomainOverviewModuleSuccess[[]HistoricalOverviewRow]]

DomainOverviewHistoryResponse wraps a historical index series in the public API data envelope.

type DomainOverviewKeywordIntent added in v0.8.0 

type DomainOverviewKeywordIntent string

DomainOverviewKeywordIntent is the provider-classified search intent. 

const (
	DomainOverviewIntentInformational DomainOverviewKeywordIntent = "informational"
	DomainOverviewIntentNavigational  DomainOverviewKeywordIntent = "navigational"
	DomainOverviewIntentCommercial    DomainOverviewKeywordIntent = "commercial"
	DomainOverviewIntentTransactional DomainOverviewKeywordIntent = "transactional"
)

type DomainOverviewKeywordsResponse added in v0.8.0 

type DomainOverviewKeywordsResponse = DataResponse[DomainOverviewModuleSuccess[DomainOverviewRankedKeywordsPage]]

DomainOverviewKeywordsResponse wraps a ranked-keyword page in the public API data envelope.

type DomainOverviewModuleOutcome added in v0.8.0 

type DomainOverviewModuleOutcome[T any] struct {
	OK        bool                         `json:"ok"`
	Cached    *bool                        `json:"cached,omitempty"`
	CostCents float64                      `json:"cost_cents"`
	Data      *T                           `json:"data,omitempty"`
	FetchedAt *time.Time                   `json:"fetched_at,omitempty"`
	Reason    *DomainOverviewFailureReason `json:"reason,omitempty"`
	ResetAt   *float64                     `json:"reset_at,omitempty"`
}

DomainOverviewModuleOutcome is a successful or failed module embedded in an analysis report. Success fields and failure fields remain pointer-valued when absent from the corresponding JSON variant; CostCents and OK are present in both variants.

type DomainOverviewModuleSuccess added in v0.8.0 

type DomainOverviewModuleSuccess[T any] struct {
	Cached    bool      `json:"cached"`
	CostCents float64   `json:"cost_cents"`
	Data      T         `json:"data"`
	FetchedAt time.Time `json:"fetched_at"`
}

DomainOverviewModuleSuccess is the top-level success data for history and table operations.

type DomainOverviewPagesResponse added in v0.8.0 

type DomainOverviewPagesResponse = DataResponse[DomainOverviewModuleSuccess[DomainOverviewRelevantPagesPage]]

DomainOverviewPagesResponse wraps a relevant-page page in the public API data envelope.

type DomainOverviewProblemErrors added in v0.8.0 

type DomainOverviewProblemErrors struct {
	CostCents float64                     `json:"cost_cents"`
	Reason    DomainOverviewFailureReason `json:"reason"`
	ResetAt   *float64                    `json:"reset_at,omitempty"`
}

DomainOverviewProblemErrors is the errors extension on a failed Domain Overview API problem. Decode APIError.Problem.Errors into this type to preserve charged cost and retry timing.

type DomainOverviewRankedKeyword added in v0.8.0 

type DomainOverviewRankedKeyword struct {
	Keyword           string                       `json:"keyword"`
	Position          *float64                     `json:"position"`
	SearchVolume      *float64                     `json:"search_volume"`
	EstimatedTraffic  *float64                     `json:"estimated_traffic"`
	CPCCents          *float64                     `json:"cpc_cents"`
	Difficulty        *float64                     `json:"difficulty"`
	Intent            *DomainOverviewKeywordIntent `json:"intent"`
	RankingURL        *string                      `json:"ranking_url"`
	SERPFeatures      []string                     `json:"serp_features"`
	RankAbsoluteDelta *float64                     `json:"rank_absolute_delta"`
	RankAbsolute      *float64                     `json:"rank_absolute"`
}

DomainOverviewRankedKeyword is one organic keyword row.

type DomainOverviewRankedKeywordsPage added in v0.8.0 

type DomainOverviewRankedKeywordsPage struct {
	Rows       []DomainOverviewRankedKeyword `json:"rows"`
	TotalCount *int                          `json:"total_count"`
	CostCents  float64                       `json:"cost_cents"`
}

DomainOverviewRankedKeywordsPage is one provider page of organic keywords.

type DomainOverviewRelevantPage added in v0.8.0 

type DomainOverviewRelevantPage struct {
	ETV                *float64 `json:"etv"`
	ETVDeltaPct        *float64 `json:"etv_delta_pct"`
	KeywordCount       *int     `json:"keyword_count"`
	Path               string   `json:"path"`
	TopKeyword         *string  `json:"top_keyword"`
	TopKeywordPosition *float64 `json:"top_keyword_position"`
}

DomainOverviewRelevantPage is one provider-ranked page for the target.

type DomainOverviewRelevantPagesPage added in v0.8.0 

type DomainOverviewRelevantPagesPage struct {
	Rows       []DomainOverviewRelevantPage `json:"rows"`
	TotalCount int                          `json:"total_count"`
	CostCents  float64                      `json:"cost_cents"`
}

DomainOverviewRelevantPagesPage is one provider page of target URLs.

type DomainOverviewReport added in v0.8.0 

type DomainOverviewReport struct {
	Cached                   bool                                                          `json:"cached"`
	CachedUntil              time.Time                                                     `json:"cached_until"`
	CostCents                float64                                                       `json:"cost_cents"`
	FetchedAt                time.Time                                                     `json:"fetched_at"`
	HistoryMode              DomainOverviewHistoryMode                                     `json:"history_mode"`
	Keywords                 DomainOverviewModuleOutcome[DomainOverviewRankedKeywordsPage] `json:"keywords"`
	LanguageCode             string                                                        `json:"language_code"`
	LocationCode             int                                                           `json:"location_code"`
	Overview                 *DomainRankMetrics                                            `json:"overview"`
	Pages                    DomainOverviewModuleOutcome[DomainOverviewRelevantPagesPage]  `json:"pages"`
	PreviousFetchedAt        *time.Time                                                    `json:"previous_fetched_at"`
	PreviousOverview         *DomainRankMetrics                                            `json:"previous_overview"`
	PreviousSourceSnapshotAt *time.Time                                                    `json:"previous_source_snapshot_at"`
	Provider                 string                                                        `json:"provider"`
	Scope                    DomainOverviewScope                                           `json:"scope"`
	SourceSnapshotAt         *time.Time                                                    `json:"source_snapshot_at"`
	State                    DomainOverviewState                                           `json:"state"`
	Target                   string                                                        `json:"target"`
}

DomainOverviewReport is the report variant returned by AnalyzeDomainOverview.

type DomainOverviewScope added in v0.8.0 

type DomainOverviewScope string

DomainOverviewScope selects a registrable root domain or one subdomain. 

const (
	DomainOverviewScopeRoot      DomainOverviewScope = "root"
	DomainOverviewScopeSubdomain DomainOverviewScope = "subdomain"
)

type DomainOverviewState added in v0.8.0 

type DomainOverviewState string

DomainOverviewState describes whether the core and optional modules returned data. 

const (
	DomainOverviewStateOK      DomainOverviewState = "ok"
	DomainOverviewStatePartial DomainOverviewState = "partial"
	DomainOverviewStateNoData  DomainOverviewState = "no_data"
)

type DomainRankMetrics added in v0.8.0 

type DomainRankMetrics struct {
	Count                     *int     `json:"count"`
	EstimatedTrafficCostCents *float64 `json:"estimated_traffic_cost_cents"`
	ETV                       *float64 `json:"etv"`
	IsDown                    int      `json:"is_down"`
	IsLost                    int      `json:"is_lost"`
	IsNew                     int      `json:"is_new"`
	IsUp                      int      `json:"is_up"`
	Pos1                      int      `json:"pos1"`
	Pos2To3                   int      `json:"pos2_3"`
	Pos4To10                  int      `json:"pos4_10"`
	Pos11To20                 int      `json:"pos11_20"`
	Pos21To30                 int      `json:"pos21_30"`
	Pos31To40                 int      `json:"pos31_40"`
	Pos41To50                 int      `json:"pos41_50"`
	Pos51To60                 int      `json:"pos51_60"`
	Pos61To70                 int      `json:"pos61_70"`
	Pos71To80                 int      `json:"pos71_80"`
	Pos81To90                 int      `json:"pos81_90"`
	Pos91To100                int      `json:"pos91_100"`
}

DomainRankMetrics contains nullable provider estimates and organic position buckets.

type EstimateFrequency 

type EstimateFrequency string

EstimateFrequency is the rank-check frequency used by GetCostEstimate to compute monthly checks. 

const (
	EstimateFrequencyDaily   EstimateFrequency = "daily"
	EstimateFrequencyWeekly  EstimateFrequency = "weekly"
	EstimateFrequencyMonthly EstimateFrequency = "monthly"
)

type ExportRankHistoryOptions 

type ExportRankHistoryOptions struct {
	Cursor      string
	Format      RankHistoryExportFormat
	Granularity RankHistoryGranularity
	KeywordIDs  []string
	Limit       int
	Range       RankHistoryExportRange
}

ExportRankHistoryOptions filters project rank history.

type FlexibleFloat 

type FlexibleFloat float64

FlexibleFloat decodes API numeric fields that may be encoded as JSON numbers or strings.

func (FlexibleFloat) Float64 

func (f FlexibleFloat) Float64() float64

Float64 returns the decoded value as a float64.

func (*FlexibleFloat) UnmarshalJSON 

func (f *FlexibleFloat) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type GetKeywordMetricsInput 

type GetKeywordMetricsInput struct {
	ConnectionID       string   `json:"connection_id,omitempty"`
	EstimateOnly       bool     `json:"estimate_only,omitempty"`
	Fresh              bool     `json:"fresh,omitempty"`
	IncludeClickstream bool     `json:"include_clickstream,omitempty"`
	Keywords           []string `json:"keywords"`
	MaxCostCents       int      `json:"max_cost_cents,omitempty"`
}

GetKeywordMetricsInput requests or estimates provider metrics for up to 700 keywords.

type HealthResponse 

type HealthResponse struct {
	Status string `json:"status"`
}

HealthResponse is returned by GetHealth.

type HistoricalOverviewRow added in v0.8.0 

type HistoricalOverviewRow struct {
	Metrics DomainRankMetrics `json:"metrics"`
	Month   int               `json:"month"`
	Year    int               `json:"year"`
}

HistoricalOverviewRow is one monthly point in the historical rank overview.

type IssuedMigrationToken 

type IssuedMigrationToken struct {
	CreatedAt time.Time      `json:"created_at"`
	ExpiresAt time.Time      `json:"expires_at"`
	ID        string         `json:"id"`
	ImportJob CloudImportJob `json:"import_job"`
	Scope     MigrationScope `json:"scope"`
	SingleUse bool           `json:"single_use"`
	Token     string         `json:"token"`
}

IssuedMigrationToken is returned once when minting a migration token.

type JSONValue 

type JSONValue map[string]any

JSONValue is used for schema-like response fields.

type Keyword 

type Keyword struct {
	ID               string           `json:"id"`
	ProjectID        string           `json:"project_id"`
	Text             string           `json:"text"`
	Country          string           `json:"country"`
	LanguageCode     string           `json:"language_code"`
	LanguageLabel    string           `json:"language_label"`
	Location         string           `json:"location"`
	LocationKey      string           `json:"location_key"`
	Device           Device           `json:"device"`
	Intent           *string          `json:"intent"`
	Topic            *string          `json:"topic"`
	TargetURL        *string          `json:"target_url"`
	RankingURL       *string          `json:"ranking_url"`
	LatestPosition   *int             `json:"latest_position"`
	PreviousPosition *int             `json:"previous_position"`
	Schedule         *KeywordSchedule `json:"schedule"`
	Tags             []string         `json:"tags"`
	CreatedAt        time.Time        `json:"created_at"`
	UpdatedAt        time.Time        `json:"updated_at"`
}

Keyword is a tracked keyword and its latest rank summary.

type KeywordBulkInput 

type KeywordBulkInput struct {
	KeywordIDs []string
	Operation  KeywordBulkOperation
	Tags       []string
	Frequency  *RankCheckFrequency
	Schedule   *KeywordScheduleInput
	TargetURL  NullableString
}

KeywordBulkInput mutates many keywords. Use StringValue or NullString for TargetURL.

func (KeywordBulkInput) MarshalJSON 

func (in KeywordBulkInput) MarshalJSON() ([]byte, error)

MarshalJSON includes only fields relevant to the selected bulk operation.

type KeywordBulkItemResult 

type KeywordBulkItemResult struct {
	KeywordID string `json:"keyword_id"`
	Status    string `json:"status"`
}

KeywordBulkItemResult is one bulk mutation result.

type KeywordBulkOperation 

type KeywordBulkOperation string

KeywordBulkOperation identifies a bulk keyword mutation. 

const (
	KeywordBulkOperationAddTags      KeywordBulkOperation = "add_tags"
	KeywordBulkOperationDelete       KeywordBulkOperation = "delete"
	KeywordBulkOperationRemoveTags   KeywordBulkOperation = "remove_tags"
	KeywordBulkOperationSetFrequency KeywordBulkOperation = "set_frequency"
	KeywordBulkOperationSetTargetURL KeywordBulkOperation = "set_target_url"
)

type KeywordBulkResponse 

type KeywordBulkResponse struct {
	Operation KeywordBulkOperation    `json:"operation"`
	Results   []KeywordBulkItemResult `json:"results"`
}

KeywordBulkResponse summarizes a bulk keyword mutation.

type KeywordIntent 

type KeywordIntent string

KeywordIntent is the provider-classified search intent. 

const (
	KeywordIntentInformational KeywordIntent = "informational"
	KeywordIntentCommercial    KeywordIntent = "commercial"
	KeywordIntentTransactional KeywordIntent = "transactional"
	KeywordIntentNavigational  KeywordIntent = "navigational"
	KeywordIntentUnknown       KeywordIntent = "unknown"
)

type KeywordMatch added in v0.4.0 

type KeywordMatch struct {
	KeywordID      string `json:"keyword_id"`
	LatestPosition *int   `json:"latest_position"`
	// PreviousPosition is the previous observed rank position, if available.
	PreviousPosition *int `json:"previous_position"`
	// RankingURL is the URL that ranked at `latest_position` in the last completed check,
	// or null when the keyword has no completed check.
	RankingURL *string            `json:"ranking_url"`
	Market     KeywordMatchMarket `json:"market"`
	// MatchedText is the trimmed, lowercased request text used to match this keyword.
	MatchedText string `json:"matched_text"`
	// Text is the stored keyword text, which can differ from MatchedText in case and whitespace.
	Text string `json:"text"`
}

KeywordMatch keeps the normalized request text separate from the stored keyword text.

type KeywordMatchMarket added in v0.4.0 

type KeywordMatchMarket struct {
	CountryCode   string `json:"country_code"`
	Device        Device `json:"device"`
	LanguageCode  string `json:"language_code"`
	LanguageLabel string `json:"language_label"`
	Location      string `json:"location"`
	LocationKey   string `json:"location_key"`
}

KeywordMatchMarket identifies one market where a keyword is tracked.

type KeywordMatchMeta added in v0.4.0 

type KeywordMatchMeta struct {
	TruncatedTexts []string `json:"truncated_texts"`
}

KeywordMatchMeta reports normalized texts with more than 100 matching markets; their returned rows are partial.

type KeywordMatchRequest added in v0.4.0 

type KeywordMatchRequest struct {
	Texts []string `json:"texts"`
}

KeywordMatchRequest identifies up to 50 keyword texts to match within a project.

type KeywordMatchResponse added in v0.4.0 

type KeywordMatchResponse struct {
	Data []KeywordMatch   `json:"data"`
	Meta KeywordMatchMeta `json:"meta"`
}

KeywordMatchResponse contains matching keywords and truncation metadata.

type KeywordMetrics 

type KeywordMetrics struct {
	Competition  *float64              `json:"competition"`
	CPCCents     *int                  `json:"cpc_cents"`
	Difficulty   *float64              `json:"difficulty"`
	Intent       *KeywordIntent        `json:"intent"`
	MonthlyTrend []KeywordMonthlyTrend `json:"monthly_trend"`
	SearchVolume *float64              `json:"search_volume"`
}

KeywordMetrics contains nullable provider metrics shared by research and hydration rows.

type KeywordMetricsResponse 

type KeywordMetricsResponse struct {
	CachedCount          int                         `json:"cached_count"`
	Connections          []KeywordResearchConnection `json:"connections"`
	CostCents            float64                     `json:"cost_cents"`
	Estimate             *bool                       `json:"estimate,omitempty"`
	EstimatedCostCents   *float64                    `json:"estimated_cost_cents,omitempty"`
	FetchedAt            time.Time                   `json:"fetched_at"`
	FetchedCount         int                         `json:"fetched_count"`
	FetchedCountEstimate *int                        `json:"fetched_count_estimate,omitempty"`
	Provider             string                      `json:"provider"`
	Rows                 []KeywordMetricsRow         `json:"rows"`
	TotalCount           int                         `json:"total_count"`
}

KeywordMetricsResponse reports cached and fetched metrics for the request.

type KeywordMetricsRow 

type KeywordMetricsRow struct {
	KeywordMetrics
	Keyword string `json:"keyword"`
}

KeywordMetricsRow is one keyword with nullable provider metrics.

type KeywordMonthlyTrend 

type KeywordMonthlyTrend struct {
	Month        int      `json:"month"`
	SearchVolume *float64 `json:"search_volume"`
	Year         int      `json:"year"`
}

KeywordMonthlyTrend is one month of provider search-volume history.

type KeywordResearchConnection 

type KeywordResearchConnection = RankedKeywordConnection

KeywordResearchConnection is an eligible project-owned DataForSEO connection.

type KeywordResearchMode 

type KeywordResearchMode string

KeywordResearchMode selects the DataForSEO Labs research source or automatic cascade. 

const (
	KeywordResearchModeAuto        KeywordResearchMode = "auto"
	KeywordResearchModeRelated     KeywordResearchMode = "related"
	KeywordResearchModeSuggestions KeywordResearchMode = "suggestions"
	KeywordResearchModeIdeas       KeywordResearchMode = "ideas"
)

type KeywordResearchResponse 

type KeywordResearchResponse struct {
	Cached      bool                           `json:"cached"`
	Connections []KeywordResearchConnection    `json:"connections"`
	CostCents   float64                        `json:"cost_cents"`
	Estimate    *bool                          `json:"estimate,omitempty"`
	FetchedAt   time.Time                      `json:"fetched_at"`
	Provider    string                         `json:"provider"`
	Rows        []KeywordResearchRow           `json:"rows"`
	Sources     []KeywordResearchSourceSummary `json:"sources"`
	TotalCount  int                            `json:"total_count"`
}

KeywordResearchResponse is one cached, paid, or estimated single-seed research result.

type KeywordResearchRow 

type KeywordResearchRow struct {
	KeywordMetrics
	AlreadyTracked bool                  `json:"already_tracked"`
	Keyword        string                `json:"keyword"`
	Source         KeywordResearchSource `json:"source"`
}

KeywordResearchRow is one researched keyword and its nullable provider metrics.

type KeywordResearchSource 

type KeywordResearchSource string

KeywordResearchSource identifies which DataForSEO Labs source returned a keyword. 

const (
	KeywordResearchSourceRelated    KeywordResearchSource = "related"
	KeywordResearchSourceSuggestion KeywordResearchSource = "suggestion"
	KeywordResearchSourceIdea       KeywordResearchSource = "idea"
)

type KeywordResearchSourceReason 

type KeywordResearchSourceReason string

KeywordResearchSourceReason explains why a research source failed or was skipped. 

const (
	KeywordResearchSourceReasonBudgetExhausted      KeywordResearchSourceReason = "budget_exhausted"
	KeywordResearchSourceReasonCostLimit            KeywordResearchSourceReason = "cost_limit"
	KeywordResearchSourceReasonInProgress           KeywordResearchSourceReason = "in_progress"
	KeywordResearchSourceReasonNeedsReauth          KeywordResearchSourceReason = "needs_reauth"
	KeywordResearchSourceReasonNoSource             KeywordResearchSourceReason = "no_source"
	KeywordResearchSourceReasonPreviousSourceFailed KeywordResearchSourceReason = "previous_source_failed"
	KeywordResearchSourceReasonProviderError        KeywordResearchSourceReason = "provider_error"
	KeywordResearchSourceReasonRateLimited          KeywordResearchSourceReason = "rate_limited"
	KeywordResearchSourceReasonResultLimit          KeywordResearchSourceReason = "result_limit"
	KeywordResearchSourceReasonUnsupportedLocation  KeywordResearchSourceReason = "unsupported_location"
)

type KeywordResearchSourceStatus 

type KeywordResearchSourceStatus string

KeywordResearchSourceStatus describes the outcome of one source in a research cascade. 

const (
	KeywordResearchSourceStatusOK      KeywordResearchSourceStatus = "ok"
	KeywordResearchSourceStatusFailed  KeywordResearchSourceStatus = "failed"
	KeywordResearchSourceStatusSkipped KeywordResearchSourceStatus = "skipped"
)

type KeywordResearchSourceSummary 

type KeywordResearchSourceSummary struct {
	Cached    bool                         `json:"cached"`
	CostCents float64                      `json:"cost_cents"`
	Reason    *KeywordResearchSourceReason `json:"reason,omitempty"`
	Returned  int                          `json:"returned"`
	Source    KeywordResearchSource        `json:"source"`
	Status    KeywordResearchSourceStatus  `json:"status"`
}

KeywordResearchSourceSummary describes one source used by a research lookup.

type KeywordSchedule 

type KeywordSchedule struct {
	CronExpression *string            `json:"cron_expression"`
	Frequency      RankCheckFrequency `json:"frequency"`
	JitterMinutes  int                `json:"jitter_minutes"`
	LastCheckedAt  *time.Time         `json:"last_checked_at"`
	NextCheckAt    *time.Time         `json:"next_check_at"`
	Timezone       string             `json:"timezone"`
}

KeywordSchedule is a keyword schedule returned by the API.

type KeywordScheduleInput 

type KeywordScheduleInput struct {
	CronExpression *string            `json:"cronExpression"`
	Frequency      RankCheckFrequency `json:"frequency"`
	JitterMinutes  *int               `json:"jitterMinutes,omitempty"`
	Timezone       string             `json:"timezone,omitempty"`
}

KeywordScheduleInput is the camelCase schedule shape accepted by write endpoints.

type ListCompetitorsResponse 

type ListCompetitorsResponse struct {
	Data []ManagedCompetitor `json:"data"`
	Meta CompetitorsMeta     `json:"meta"`
}

ListCompetitorsResponse is returned by ListCompetitors.

type ListKeywordsOptions 

type ListKeywordsOptions struct {
	Cursor     string
	Limit      int
	Country    string
	Device     Device
	Intent     string
	PositionGT int
	PositionLT int
	Search     string
	Sort       string
	Tag        string
	Topic      string
}

ListKeywordsOptions filters project keywords. Intent and Topic are case-insensitive exact filters up to 80 characters.

type ListMeta 

type ListMeta struct {
	NextCursor *string `json:"next_cursor"`
}

ListMeta contains pagination metadata.

type ListMigrationTokensResponse 

type ListMigrationTokensResponse struct {
	Data []MigrationToken    `json:"data"`
	Meta MigrationTokensMeta `json:"meta"`
}

ListMigrationTokensResponse is returned by ListMigrationTokens.

type ListRankChecksOptions 

type ListRankChecksOptions struct {
	Cursor string
	Limit  int
	Since  time.Time
	Status RankCheckStatus
	Until  time.Time
}

ListRankChecksOptions filters rank check history.

type ListRankedKeywordSuggestionsOptions 

type ListRankedKeywordSuggestionsOptions struct {
	ConnectionID string
	Fresh        bool
	Limit        int
	Offset       int
}

ListRankedKeywordSuggestionsOptions controls one offset-paginated ranked keyword lookup.

type ListResponse 

type ListResponse[T any] struct {
	Data []T      `json:"data"`
	Meta ListMeta `json:"meta"`
}

ListResponse is returned by paginated list endpoints.

type ListSearchPerformanceQueryStatsOptions 

type ListSearchPerformanceQueryStatsOptions struct {
	ConnectionID string
	EndDate      string
	Limit        int
	Query        string
	StartDate    string
}

ListSearchPerformanceQueryStatsOptions controls a live connected-provider query.

type ListSignalsOptions 

type ListSignalsOptions struct {
	Cursor string
	Limit  int
	From   time.Time
	Source SignalSource
	To     time.Time
	Type   string
}

ListSignalsOptions filters project signals. Signals are returned newest first by happened_at.

type ListTrafficSnapshotsOptions 

type ListTrafficSnapshotsOptions struct {
	EndDate   string
	Limit     int
	Offset    int
	Paths     []string
	StartDate string
}

ListTrafficSnapshotsOptions filters stored page traffic snapshots by date and path.

type LivenessResponse added in v0.6.0 

type LivenessResponse struct {
	Status string `json:"status"`
}

LivenessResponse is returned by GetLiveness.

type LoadDomainOverviewHistoryOptions added in v0.8.0 

type LoadDomainOverviewHistoryOptions struct {
	Target        string               `json:"target"`
	LocationCode  int                  `json:"location_code"`
	LanguageCode  string               `json:"language_code"`
	ScopeOverride *DomainOverviewScope `json:"scope_override,omitempty"`
	Fresh         *bool                `json:"fresh,omitempty"`
	MaxCostCents  int                  `json:"max_cost_cents"`
}

LoadDomainOverviewHistoryOptions controls a historical index load.

type LoadDomainOverviewKeywordsOptions added in v0.8.0 

type LoadDomainOverviewKeywordsOptions struct {
	Target        string               `json:"target"`
	LocationCode  int                  `json:"location_code"`
	LanguageCode  string               `json:"language_code"`
	ScopeOverride *DomainOverviewScope `json:"scope_override,omitempty"`
	Fresh         *bool                `json:"fresh,omitempty"`
	MaxCostCents  int                  `json:"max_cost_cents"`
	Limit         int                  `json:"limit"`
	Offset        int                  `json:"offset"`
}

LoadDomainOverviewKeywordsOptions controls one ranked-keyword page load.

type LoadDomainOverviewPagesOptions added in v0.8.0 

type LoadDomainOverviewPagesOptions = LoadDomainOverviewKeywordsOptions

LoadDomainOverviewPagesOptions controls one relevant-page page load.

type LoadMoreBacklinkRowsOptions added in v0.4.0 

type LoadMoreBacklinkRowsOptions struct {
	Target            string              `json:"target"`
	TargetScope       BacklinkTargetScope `json:"target_scope"`
	IncludeSubdomains bool                `json:"include_subdomains"`
	Limit             int                 `json:"limit"`
}

LoadMoreBacklinkRowsOptions selects rows to append to an unexpired snapshot.

type LocationKind 

type LocationKind string

LocationKind identifies the level represented by a location suggestion. 

const (
	LocationKindCountry LocationKind = "country"
	LocationKindRegion  LocationKind = "region"
	LocationKindCity    LocationKind = "city"
)

type LocationSuggestion 

type LocationSuggestion struct {
	CityName      *string      `json:"city_name"`
	CountryCode   string       `json:"country_code"`
	DisplayName   string       `json:"display_name"`
	HL            string       `json:"hl"`
	Kind          LocationKind `json:"kind"`
	LanguageCode  string       `json:"language_code"`
	LanguageLabel string       `json:"language_label"`
	LocationKey   string       `json:"location_key"`
	RegionCode    *string      `json:"region_code"`
	RegionName    *string      `json:"region_name"`
}

LocationSuggestion is a canonical country, region, or city location.

type LocationSuggestionsResponse 

type LocationSuggestionsResponse struct {
	Data []LocationSuggestion `json:"data"`
	Meta ListMeta             `json:"meta"`
}

LocationSuggestionsResponse contains canonical locations and compatibility pagination metadata.

type ManagedCompetitor 

type ManagedCompetitor struct {
	Domain   string `json:"domain"`
	ID       string `json:"id"`
	Initials string `json:"initials,omitempty"`
	Label    string `json:"label"`
}

ManagedCompetitor is a competitor item in the project competitor list.

type Me 

type Me struct {
	Email    string      `json:"email"`
	ID       string      `json:"id"`
	Name     string      `json:"name"`
	Projects []MeProject `json:"projects"`
}

Me is the authenticated personal access token user.

type MeProject 

type MeProject struct {
	Domain string        `json:"domain"`
	ID     string        `json:"id"`
	Name   string        `json:"name"`
	Role   TeamRoleValue `json:"role"`
}

MeProject is one project membership returned by GetMe.

type MigrationScope 

type MigrationScope string

MigrationScope selects which data a migration token can import. 

const (
	MigrationScopeFull     MigrationScope = "full"
	MigrationScopeKeywords MigrationScope = "keywords"
)

type MigrationToken 

type MigrationToken struct {
	CreatedAt time.Time               `json:"created_at"`
	CreatedBy MigrationTokenCreatedBy `json:"created_by"`
	ExpiresAt time.Time               `json:"expires_at"`
	ID        string                  `json:"id"`
	Scope     MigrationScope          `json:"scope"`
	SingleUse bool                    `json:"single_use"`
}

MigrationToken is an active migration token without the raw token value.

type MigrationTokenCreatedBy 

type MigrationTokenCreatedBy struct {
	Email string `json:"email"`
	Name  string `json:"name"`
}

MigrationTokenCreatedBy identifies who minted an active migration token.

type MigrationTokensMeta 

type MigrationTokensMeta struct {
	NextCursor *string        `json:"next_cursor"`
	ImportJob  CloudImportJob `json:"import_job"`
}

MigrationTokensMeta contains list pagination plus import job metadata.

type MintMigrationTokenInput 

type MintMigrationTokenInput struct {
	Scope MigrationScope `json:"scope,omitempty"`
}

MintMigrationTokenInput creates a migration token.

type NetworkError 

type NetworkError struct {
	Cause  error
	Method string
	URL    string
}

NetworkError wraps transport-level failures while calling the Bisibility API.

func (*NetworkError) Error 

func (e *NetworkError) Error() string

func (*NetworkError) Unwrap 

func (e *NetworkError) Unwrap() error

type NotificationPreferences 

type NotificationPreferences struct {
	AlertEmail        bool   `json:"alert_email"`
	AlertInApp        bool   `json:"alert_in_app"`
	AlertSlack        bool   `json:"alert_slack"`
	AlertWebhook      bool   `json:"alert_webhook"`
	CheckEmail        bool   `json:"check_email"`
	CheckInApp        bool   `json:"check_in_app"`
	Email             string `json:"email"`
	EmailVerification string `json:"email_verification"`
	ImportEmail       bool   `json:"import_email"`
	ImportInApp       bool   `json:"import_in_app"`
	InviteEmail       bool   `json:"invite_email"`
	InviteInApp       bool   `json:"invite_in_app"`
	ProjectID         string `json:"project_id"`
	SlackAvailable    bool   `json:"slack_available"`
	WebhookAvailable  bool   `json:"webhook_available"`
}

NotificationPreferences are the full notification preferences returned by GET.

type NullableString 

type NullableString struct {
	// contains filtered or unexported fields
}

NullableString represents an optional string field that can be explicitly set to null.

func NullString 

func NullString() NullableString

NullString returns a NullableString explicitly set to JSON null.

func StringValue 

func StringValue(value string) NullableString

StringValue returns a NullableString set to a concrete string value.

func (NullableString) IsSet 

func (n NullableString) IsSet() bool

IsSet reports whether the field should be included in a request body.

func (NullableString) MarshalJSON 

func (n NullableString) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (NullableString) Value 

func (n NullableString) Value() *string

Value returns the underlying string pointer. A nil pointer means JSON null when IsSet is true.

type OpenAPIDocument 

type OpenAPIDocument struct {
	OpenAPI    string         `json:"openapi"`
	Info       JSONValue      `json:"info"`
	Paths      JSONValue      `json:"paths"`
	Components JSONValue      `json:"components,omitempty"`
	Servers    []JSONValue    `json:"servers,omitempty"`
	Extra      map[string]any `json:"-"`
}

OpenAPIDocument is the OpenAPI document returned by GetOpenAPI.

type Option 

type Option func(*Client) error

Option configures a Client.

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey configures the bearer API key used for protected API methods.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL configures the API v1 root URL.

func WithDefaultHeader 

func WithDefaultHeader(key, value string) Option

WithDefaultHeader configures a header sent with every request.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient configures the HTTP client. The default is an *http.Client with a 30 second timeout; supply your own client to change the timeout, transport, or proxy behavior.

func WithMaxRetries 

func WithMaxRetries(maxRetries int) Option

WithMaxRetries sets retries after the initial attempt. The default is 2.

func WithProjectID 

func WithProjectID(projectID string) Option

WithProjectID configures the project targeted by personal access token requests on routes without a project in the path. A strict public project ID is sent as the X-Bisibility-Project header with every request; override it per request with WithRequestHeader.

type PageTrafficSnapshot 

type PageTrafficSnapshot struct {
	BounceRate           *float64  `json:"bounce_rate"`
	CreatedAt            time.Time `json:"created_at"`
	Date                 string    `json:"date"`
	EngagementRate       *float64  `json:"engagement_rate"`
	KeyEvents            *float64  `json:"key_events"`
	Path                 string    `json:"path"`
	Provider             string    `json:"provider"`
	ScrollDepth          *float64  `json:"scroll_depth"`
	Sessions             int       `json:"sessions"`
	UpdatedAt            time.Time `json:"updated_at"`
	VisitDurationSeconds *float64  `json:"visit_duration_seconds"`
	Visitors             *int      `json:"visitors"`
	WindowDays           int       `json:"window_days"`
}

PageTrafficSnapshot is one stored page analytics observation.

type PageTrafficSnapshotsResponse 

type PageTrafficSnapshotsResponse struct {
	Offset     int                   `json:"offset"`
	Rows       []PageTrafficSnapshot `json:"rows"`
	TotalCount int                   `json:"total_count"`
}

PageTrafficSnapshotsResponse is one offset-paginated page of traffic snapshots.

type Pager 

type Pager[T any] struct {
	// contains filtered or unexported fields
}

Pager iterates cursor-paginated resources on Go versions before iter.Seq2. Call Next, read Item, and check Err after iteration stops.

func (*Pager[T]) Err 

func (p *Pager[T]) Err() error

Err returns the first page-fetch error, if any.

func (*Pager[T]) Item 

func (p *Pager[T]) Item() T

Item returns the current item after Next returns true.

func (*Pager[T]) Next 

func (p *Pager[T]) Next() bool

Next advances to the next item, fetching another page when necessary.

type PaginationOptions 

type PaginationOptions struct {
	Cursor string
	Limit  int
}

PaginationOptions configures cursor pagination.

type PersonalAccessToken 

type PersonalAccessToken struct {
	CreatedAt  time.Time  `json:"created_at"`
	ExpiresAt  *time.Time `json:"expires_at"`
	ID         string     `json:"id"`
	LastUsedAt *time.Time `json:"last_used_at"`
	Name       string     `json:"name"`
	Prefix     string     `json:"prefix"`
	RevokedAt  *time.Time `json:"revoked_at"`
	Scope      TokenScope `json:"scope"`
}

PersonalAccessToken describes a personal access token without the raw secret.

type PricingModel 

type PricingModel string

PricingModel identifies how a provider rate card is priced. 

const (
	PricingModelFlat PricingModel = "flat"
	PricingModelPlan PricingModel = "plan"
)

type ProblemDetails 

type ProblemDetails struct {
	Type     string          `json:"type"`
	Title    string          `json:"title"`
	Status   int             `json:"status"`
	Detail   string          `json:"detail"`
	Instance string          `json:"instance"`
	DocsURL  string          `json:"docs_url"`
	Errors   json.RawMessage `json:"errors,omitempty"`
	// Extensions preserves RFC 9457 extension members not known to this SDK.
	Extensions map[string]json.RawMessage `json:"-"`
}

ProblemDetails is the Bisibility RFC problem details error body.

func (*ProblemDetails) UnmarshalJSON 

func (p *ProblemDetails) UnmarshalJSON(data []byte) error

UnmarshalJSON tolerates mistyped known members while preserving extension members.

type Project 

type Project struct {
	ID        string           `json:"id"`
	Name      string           `json:"name"`
	Domain    string           `json:"domain"`
	WriteMode ProjectWriteMode `json:"write_mode"`
	CreatedAt time.Time        `json:"created_at"`
	UpdatedAt time.Time        `json:"updated_at"`
}

Project is a Bisibility project visible to an API key.

type ProjectDefaults 

type ProjectDefaults struct {
	City            *string               `json:"city"`
	Country         string                `json:"country"`
	CronExpression  *string               `json:"cron_expression"`
	Device          Device                `json:"device"`
	Frequency       RankCheckFrequency    `json:"frequency"`
	JitterMinutes   int                   `json:"jitter_minutes"`
	LastCheckedAt   *time.Time            `json:"last_checked_at"`
	LocationKey     string                `json:"location_key"`
	NextCheckAt     *time.Time            `json:"next_check_at"`
	ProjectID       string                `json:"project_id"`
	SerpDepth       int                   `json:"serp_depth"`
	SerpStopOnMatch bool                  `json:"serp_stop_on_match"`
	Source          ProjectDefaultsSource `json:"source"`
	Timezone        string                `json:"timezone"`
	UpdatedAt       *time.Time            `json:"updated_at"`
}

ProjectDefaults are the project default market and schedule settings.

type ProjectDefaultsPatch 

type ProjectDefaultsPatch struct {
	City            *string            `json:"city,omitempty"`
	Country         string             `json:"country,omitempty"`
	CronExpression  *string            `json:"cron_expression,omitempty"`
	Device          Device             `json:"device,omitempty"`
	Frequency       RankCheckFrequency `json:"frequency"`
	JitterMinutes   *int               `json:"jitter_minutes,omitempty"`
	LocationKey     string             `json:"location_key,omitempty"`
	SerpStopOnMatch *bool              `json:"serp_stop_on_match,omitempty"`
	Timezone        string             `json:"timezone,omitempty"`
}

ProjectDefaultsPatch updates project default market and schedule settings. Frequency is required by the API. Country and Device must be provided together when LocationKey is omitted. Omitted schedule fields fall back to server defaults (jitter_minutes 60 and timezone UTC).

type ProjectDefaultsSource 

type ProjectDefaultsSource string

ProjectDefaultsSource identifies how the effective default market was selected. 

const (
	ProjectDefaultsSourceDerived  ProjectDefaultsSource = "derived"
	ProjectDefaultsSourceExplicit ProjectDefaultsSource = "explicit"
	ProjectDefaultsSourceFallback ProjectDefaultsSource = "fallback"
)

type ProjectOverview added in v0.4.0 

type ProjectOverview struct {
	AveragePosition        *float64                        `json:"average_position"`
	AveragePositionDelta   *float64                        `json:"average_position_delta"`
	KeywordsAddedThisMonth int                             `json:"keywords_added_this_month"`
	LastCheckAt            *time.Time                      `json:"last_check_at"`
	NextCheckAt            *time.Time                      `json:"next_check_at"`
	PositionDistribution   []ProjectOverviewPositionBucket `json:"position_distribution"`
	ProjectID              string                          `json:"project_id"`
	Top10Count             *int                            `json:"top_10_count"`
	Top10Delta             *int                            `json:"top_10_delta"`
	Top100Count            *int                            `json:"top_100_count"`
	Top3Count              *int                            `json:"top_3_count"`
	TrackedKeywordCount    int                             `json:"tracked_keyword_count"`
	Visibility             *float64                        `json:"visibility"`
	VisibilityDelta        *float64                        `json:"visibility_delta"`
}

ProjectOverview summarizes tracked keyword rank performance for a project.

type ProjectOverviewDevice added in v0.4.0 

type ProjectOverviewDevice string

ProjectOverviewDevice identifies the SERP device filter used for an overview. 

const (
	ProjectOverviewDeviceAll     ProjectOverviewDevice = "all"
	ProjectOverviewDeviceDesktop ProjectOverviewDevice = "desktop"
	ProjectOverviewDeviceMobile  ProjectOverviewDevice = "mobile"
)

type ProjectOverviewOptions added in v0.4.0 

type ProjectOverviewOptions struct {
	Device ProjectOverviewDevice
	Range  ProjectOverviewRange
	Tag    string
}

ProjectOverviewOptions filters a project overview.

type ProjectOverviewPositionBucket added in v0.4.0 

type ProjectOverviewPositionBucket struct {
	Count *int `json:"count"`
	Max   int  `json:"max"`
	Min   int  `json:"min"`
}

ProjectOverviewPositionBucket counts keywords within an inclusive position range.

type ProjectOverviewRange added in v0.4.0 

type ProjectOverviewRange string

ProjectOverviewRange identifies the rank-history window used for overview comparisons. 

const (
	ProjectOverviewRange7Days  ProjectOverviewRange = "7d"
	ProjectOverviewRange28Days ProjectOverviewRange = "28d"
	ProjectOverviewRange90Days ProjectOverviewRange = "90d"
)

type ProjectWriteMode 

type ProjectWriteMode string

ProjectWriteMode reports whether a project accepts writes. 

const (
	ProjectWriteModeActive        ProjectWriteMode = "active"
	ProjectWriteModeMigrationHold ProjectWriteMode = "migration_hold"
	ProjectWriteModeMigrated      ProjectWriteMode = "migrated"
)

type Provider 

type Provider struct {
	CategoryID      string            `json:"category_id"`
	CategoryTitle   string            `json:"category_title"`
	Description     string            `json:"description"`
	Drawer          ProviderDrawer    `json:"drawer"`
	Enabled         *bool             `json:"enabled,omitempty"`
	Icon            string            `json:"icon"`
	ID              ProviderID        `json:"id"`
	LogoDomain      string            `json:"logo_domain,omitempty"`
	Meta            []ProviderMetaRow `json:"meta"`
	Name            string            `json:"name"`
	Primary         *bool             `json:"primary,omitempty"`
	Priority        *int              `json:"priority,omitempty"`
	SecondaryAction string            `json:"secondary_action,omitempty"`
	Status          ProviderStatus    `json:"status"`
	Tint            string            `json:"tint"`
}

Provider is one provider catalog item returned by ListProviders.

type ProviderConnection 

type ProviderConnection struct {
	CostPerCheckCents *FlexibleFloat `json:"cost_per_check_cents,omitempty"`
	CreatedAt         *time.Time     `json:"created_at,omitempty"`
	CredentialsHash   *string        `json:"credentials_hash,omitempty"`
	Enabled           bool           `json:"enabled"`
	ID                string         `json:"id"`
	IsPrimary         bool           `json:"is_primary"`
	Kind              ProviderKind   `json:"kind"`
	LastUsedAt        *time.Time     `json:"last_used_at,omitempty"`
	Priority          int            `json:"priority"`
	ProjectID         string         `json:"project_id"`
	Provider          ProviderID     `json:"provider"`
	Status            ProviderStatus `json:"status"`
	UpdatedAt         *time.Time     `json:"updated_at,omitempty"`
}

ProviderConnection is returned by provider connect and settings endpoints.

type ProviderCredentialField 

type ProviderCredentialField struct {
	Label       string `json:"label"`
	Name        string `json:"name"`
	Placeholder string `json:"placeholder"`
	Type        string `json:"type,omitempty"`
}

ProviderCredentialField describes one credential field required by a provider.

type ProviderCredentialsInput 

type ProviderCredentialsInput struct {
	APIKey   string `json:"api_key,omitempty"`
	Endpoint string `json:"endpoint,omitempty"`
	Login    string `json:"login,omitempty"`
	Secret   string `json:"secret,omitempty"`
}

ProviderCredentialsInput contains provider credentials for connect and test requests.

type ProviderDisconnectResult 

type ProviderDisconnectResult struct {
	OK bool `json:"ok"`
}

ProviderDisconnectResult is returned by DisconnectProvider.

type ProviderDrawer 

type ProviderDrawer struct {
	Activities         []ProviderMetaRow         `json:"activities"`
	CostHelp           string                    `json:"cost_help"`
	CredentialFields   []ProviderCredentialField `json:"credential_fields"`
	Defaults           ProviderDrawerDefaults    `json:"defaults"`
	EnvHint            string                    `json:"env_hint"`
	PrimaryToggleLabel string                    `json:"primary_toggle_label"`
}

ProviderDrawer contains provider configuration metadata.

type ProviderDrawerDefaults 

type ProviderDrawerDefaults struct {
	CostPerCheck float64 `json:"cost_per_check"`
	Depth        string  `json:"depth"`
	Device       string  `json:"device"`
	Enabled      *bool   `json:"enabled,omitempty"`
	Language     string  `json:"language"`
	Location     string  `json:"location"`
	Login        string  `json:"login"`
	Primary      bool    `json:"primary"`
	Priority     *int    `json:"priority,omitempty"`
	Secret       string  `json:"secret"`
}

ProviderDrawerDefaults contains default UI values returned with provider catalog entries.

type ProviderID 

type ProviderID string

ProviderID identifies a supported provider. The connectable provider ids accepted by connect, test, settings, and disconnect endpoints are dataforseo, serpapi, gsc, ga4, and plausible; ahrefs and semrush only appear in catalog listings. 

const (
	ProviderIDDataForSEO ProviderID = "dataforseo"
	ProviderIDSerpAPI    ProviderID = "serpapi"
	ProviderIDGSC        ProviderID = "gsc"
	ProviderIDGA4        ProviderID = "ga4"
	ProviderIDPlausible  ProviderID = "plausible"
	ProviderIDAhrefs     ProviderID = "ahrefs"
	ProviderIDSemrush    ProviderID = "semrush"
)

type ProviderKind 

type ProviderKind string

ProviderKind identifies the provider category. 

const (
	ProviderKindSERP       ProviderKind = "serp"
	ProviderKindAnalytics  ProviderKind = "analytics"
	ProviderKindEnrichment ProviderKind = "enrichment"
)

type ProviderMetaRow 

type ProviderMetaRow struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

ProviderMetaRow is one label/value row on provider catalog responses.

type ProviderPrioritySyncError added in v0.7.0 

type ProviderPrioritySyncError struct {
	Cause error
}

ProviderPrioritySyncError reports a priority PATCH failure after a provider connect succeeds.

func (*ProviderPrioritySyncError) Error added in v0.7.0 

func (e *ProviderPrioritySyncError) Error() string

func (*ProviderPrioritySyncError) Unwrap added in v0.7.0 

func (e *ProviderPrioritySyncError) Unwrap() error

type ProviderRate 

type ProviderRate struct {
	CheckedAt    string               `json:"checked_at"`
	Label        string               `json:"label"`
	Notes        string               `json:"notes,omitempty"`
	Options      []ProviderRateOption `json:"options,omitempty"`
	Plans        []ProviderRatePlan   `json:"plans,omitempty"`
	PricingModel PricingModel         `json:"pricing_model"`
	ProviderID   ProviderID           `json:"provider_id"`
	SourceURL    string               `json:"source_url"`
}

ProviderRate is one public SERP provider rate card. Flat rate cards carry Options and plan rate cards carry Plans.

type ProviderRateOption 

type ProviderRateOption struct {
	Key           string  `json:"key"`
	Label         string  `json:"label"`
	ShortLabel    string  `json:"short_label"`
	Turnaround    string  `json:"turnaround"`
	UnitCostCents float64 `json:"unit_cost_cents"`
	UnitCostUSD   float64 `json:"unit_cost_usd"`
}

ProviderRateOption is one flat-rate pricing option on a provider rate card.

type ProviderRatePlan 

type ProviderRatePlan struct {
	IncludedChecks    int     `json:"included_checks"`
	Label             string  `json:"label"`
	MonthlyPriceCents float64 `json:"monthly_price_cents"`
	MonthlyPriceUSD   float64 `json:"monthly_price_usd"`
	PlanKey           string  `json:"plan_key"`
}

ProviderRatePlan is one subscription plan tier on a provider rate card.

type ProviderSettingsInput 

type ProviderSettingsInput struct {
	Enabled  *bool `json:"enabled,omitempty"`
	Primary  *bool `json:"primary,omitempty"`
	Priority *int  `json:"priority,omitempty"`
}

ProviderSettingsInput updates provider enabled, primary, and priority settings.

type ProviderStatus 

type ProviderStatus string

ProviderStatus is a provider connection or catalog status. 

const (
	ProviderStatusConnected   ProviderStatus = "connected"
	ProviderStatusNeedsReauth ProviderStatus = "needs_reauth"
	ProviderStatusOptional    ProviderStatus = "optional"
	ProviderStatusPlanned     ProviderStatus = "planned"
	ProviderStatusReady       ProviderStatus = "ready"
)

type ProviderTestResult 

type ProviderTestResult struct {
	Balance *float64 `json:"balance,omitempty"`
	Message string   `json:"message"`
	OK      bool     `json:"ok"`
}

ProviderTestResult is returned by TestProviderConnection.

type PublicIDPrefix added in v0.5.0 

type PublicIDPrefix string

PublicIDPrefix identifies the public resource namespace encoded in an ID. A public ID is always prefix_[a-z][a-z0-9]{23}. 

const (
	PublicIDPrefixAlert   PublicIDPrefix = "al"
	PublicIDPrefixRule    PublicIDPrefix = "alr"
	PublicIDPrefixAudit   PublicIDPrefix = "audit"
	PublicIDPrefixCheck   PublicIDPrefix = "check"
	PublicIDPrefixComp    PublicIDPrefix = "cmp"
	PublicIDPrefixConn    PublicIDPrefix = "conn"
	PublicIDPrefixHook    PublicIDPrefix = "dwh"
	PublicIDPrefixMToken  PublicIDPrefix = "ferry"
	PublicIDPrefixJob     PublicIDPrefix = "imp"
	PublicIDPrefixInvite  PublicIDPrefix = "inv"
	PublicIDPrefixKey     PublicIDPrefix = "key"
	PublicIDPrefixKeyword PublicIDPrefix = "kw"
	PublicIDPrefixMember  PublicIDPrefix = "mbr"
	PublicIDPrefixNotif   PublicIDPrefix = "ntf"
	PublicIDPrefixPAT     PublicIDPrefix = "pat"
	PublicIDPrefixProject PublicIDPrefix = "prj"
	PublicIDPrefixSession PublicIDPrefix = "sid"
	PublicIDPrefixSignal  PublicIDPrefix = "sig"
	PublicIDPrefixSKW     PublicIDPrefix = "svkw"
	PublicIDPrefixTag     PublicIDPrefix = "tag"
	PublicIDPrefixUser    PublicIDPrefix = "usr"
	PublicIDPrefixView    PublicIDPrefix = "viw"
	PublicIDPrefixWebhook PublicIDPrefix = "we"
)

type RankCheck 

type RankCheck struct {
	ID               string             `json:"id"`
	KeywordID        string             `json:"keyword_id"`
	Attempts         []RankCheckAttempt `json:"attempts"`
	CheckedAt        time.Time          `json:"checked_at"`
	CostCents        *float64           `json:"cost_cents"`
	Error            *string            `json:"error"`
	Position         *int               `json:"position"`
	PreviousPosition *int               `json:"previous_position"`
	Provider         string             `json:"provider"`
	RankingURL       *string            `json:"ranking_url"`
	Status           string             `json:"status"`
}

RankCheck is a keyword rank check. Status is running for async checks that have not completed yet.

type RankCheckAttempt 

type RankCheckAttempt struct {
	Message  string `json:"message"`
	Provider string `json:"provider"`
}

RankCheckAttempt is one provider fallback attempt recorded before the final rank-check status.

type RankCheckFrequency 

type RankCheckFrequency string

RankCheckFrequency controls how often Bisibility checks a keyword. 

const (
	RankCheckFrequencyPaused     RankCheckFrequency = "paused"
	RankCheckFrequencyManual     RankCheckFrequency = "manual"
	RankCheckFrequencyDaily      RankCheckFrequency = "daily"
	RankCheckFrequencyWeekly     RankCheckFrequency = "weekly"
	RankCheckFrequencyMonthly    RankCheckFrequency = "monthly"
	RankCheckFrequencyCustomCron RankCheckFrequency = "custom_cron"
)

type RankCheckStatus 

type RankCheckStatus string

RankCheckStatus is the status filter for rank check history. 

const (
	RankCheckStatusCompleted RankCheckStatus = "completed"
	RankCheckStatusFailed    RankCheckStatus = "failed"
	RankCheckStatusRunning   RankCheckStatus = "running"
)

type RankHistoryExportFormat 

type RankHistoryExportFormat string

RankHistoryExportFormat selects the rank-history response representation. 

const (
	RankHistoryExportFormatJSON RankHistoryExportFormat = "json"
	RankHistoryExportFormatCSV  RankHistoryExportFormat = "csv"
)

type RankHistoryExportRange 

type RankHistoryExportRange string

RankHistoryExportRange selects the history window. 

const (
	RankHistoryExportRange30Days RankHistoryExportRange = "30"
	RankHistoryExportRange90Days RankHistoryExportRange = "90"
	RankHistoryExportRangeAll    RankHistoryExportRange = "all"
)

type RankHistoryExportResponse 

type RankHistoryExportResponse struct {
	CSV    string                  `json:"-"`
	Data   []RankHistoryExportRow  `json:"data"`
	Format RankHistoryExportFormat `json:"-"`
	Meta   ListMeta                `json:"meta"`
}

RankHistoryExportResponse contains either a JSON page or a complete CSV document. Format identifies which representation is populated.

type RankHistoryExportRow 

type RankHistoryExportRow struct {
	CheckedAt        time.Time `json:"checked_at"`
	ID               string    `json:"id"`
	Keyword          string    `json:"keyword"`
	KeywordID        string    `json:"keyword_id"`
	Position         *int      `json:"position"`
	PreviousPosition *int      `json:"previous_position"`
	RankingURL       *string   `json:"ranking_url"`
}

RankHistoryExportRow is one exported rank-check result.

type RankHistoryGranularity 

type RankHistoryGranularity string

RankHistoryGranularity controls export aggregation. 

const (
	RankHistoryGranularityDaily  RankHistoryGranularity = "daily"
	RankHistoryGranularityWeekly RankHistoryGranularity = "weekly"
)

type RankedKeywordConnection 

type RankedKeywordConnection struct {
	ID       string     `json:"id"`
	Label    string     `json:"label"`
	Provider ProviderID `json:"provider"`
}

RankedKeywordConnection is an eligible project-owned DataForSEO connection.

type RankedKeywordSuggestion 

type RankedKeywordSuggestion struct {
	AlreadyTracked   bool     `json:"already_tracked"`
	EstimatedTraffic *float64 `json:"estimated_traffic"`
	Keyword          string   `json:"keyword"`
	Position         *int     `json:"position"`
	SearchVolume     *float64 `json:"search_volume"`
}

RankedKeywordSuggestion is one query for which the project domain already ranks.

type RankedKeywordSuggestionsResponse 

type RankedKeywordSuggestionsResponse struct {
	Cached      bool                      `json:"cached"`
	Connections []RankedKeywordConnection `json:"connections"`
	CostCents   float64                   `json:"cost_cents"`
	FetchedAt   time.Time                 `json:"fetched_at"`
	Offset      int                       `json:"offset"`
	Rows        []RankedKeywordSuggestion `json:"rows"`
	TotalCount  *int                      `json:"total_count"`
}

RankedKeywordSuggestionsResponse is one cached or paid ranked keyword page.

type ReadinessResponse added in v0.6.0 

type ReadinessResponse struct {
	Status string `json:"status"`
}

ReadinessResponse is returned by GetReadiness.

type RequestOption 

type RequestOption func(*requestConfig)

RequestOption configures an individual API request.

func WithIdempotencyKey 

func WithIdempotencyKey(key string) RequestOption

WithIdempotencyKey sets the Idempotency-Key header for a write request.

func WithRequestHeader 

func WithRequestHeader(key, value string) RequestOption

WithRequestHeader sets one header for an individual API request.

type ResearchKeywordsOptions 

type ResearchKeywordsOptions struct {
	ConnectionID       string
	EstimateOnly       bool
	Fresh              bool
	IncludeClickstream bool
	MaxCostCents       int
	Mode               KeywordResearchMode
	ResultLimit        int
	Seed               string
}

ResearchKeywordsOptions controls a paid or estimated single-seed keyword research lookup.

type ResponseError 

type ResponseError struct {
	Body       string
	Cause      error
	Method     string
	StatusCode int
	URL        string
}

ResponseError reports invalid successful API responses, such as malformed JSON.

func (*ResponseError) Error 

func (e *ResponseError) Error() string

func (*ResponseError) Unwrap 

func (e *ResponseError) Unwrap() error

type RevokeTeamInviteResult 

type RevokeTeamInviteResult struct {
	ID string `json:"id"`
}

RevokeTeamInviteResult is returned after revoking an invite.

type RevokedMigrationToken 

type RevokedMigrationToken struct {
	ID        string    `json:"id"`
	RevokedAt time.Time `json:"revoked_at"`
}

RevokedMigrationToken is returned after revoking a migration token.

type RunRankCheckInput 

type RunRankCheckInput struct {
	ProviderID string `json:"provider_id,omitempty"`
	Async      bool   `json:"-"`
}

RunRankCheckInput selects an optional provider for an immediate rank check. Set Async to enqueue the check instead of waiting for the result: the API responds 202 with a RankCheck in status running. Poll GetRankCheckResult until the status becomes completed or failed.

type SavedKeyword added in v0.6.0 

type SavedKeyword struct {
	CPC          *float64                 `json:"cpc"`
	Difficulty   *int                     `json:"difficulty"`
	ID           string                   `json:"id"`
	Intent       *string                  `json:"intent"`
	Location     string                   `json:"location"`
	SavedAt      time.Time                `json:"saved_at"`
	SourceSeed   *string                  `json:"source_seed"`
	Text         string                   `json:"text"`
	Trend        []SavedKeywordTrendPoint `json:"trend"`
	VariantCount int                      `json:"variant_count"`
	Volume       *int                     `json:"volume"`
}

SavedKeyword is a keyword saved from keyword research. Provider metrics are nullable because the API stores whatever the research response carried.

type SavedKeywordDeleteResult added in v0.6.0 

type SavedKeywordDeleteResult struct {
	RemovedCount int `json:"removed_count"`
}

SavedKeywordDeleteResult is returned after deleting a saved keyword.

type SavedKeywordInput added in v0.6.0 

type SavedKeywordInput struct {
	CPCCents     *int   `json:"cpc_cents,omitempty"`
	Difficulty   *int   `json:"difficulty,omitempty"`
	Intent       string `json:"intent,omitempty"`
	Keyword      string `json:"keyword"`
	Location     string `json:"location,omitempty"`
	SearchVolume *int   `json:"search_volume,omitempty"`
	SourceSeed   string `json:"source_seed,omitempty"`
	VariantCount *int   `json:"variant_count,omitempty"`
}

SavedKeywordInput is one keyword saved by CreateSavedKeywords. Only Keyword is required; the API substitutes the project default market when Location is empty and stores the remaining metrics as supplied.

type SavedKeywordItem added in v0.6.0 

type SavedKeywordItem interface {
	// contains filtered or unexported methods
}

SavedKeywordItem accepts either a bare keyword string or a metric snapshot.

type SavedKeywordResult added in v0.6.0 

type SavedKeywordResult struct {
	Keyword string             `json:"keyword"`
	Status  SavedKeywordStatus `json:"status"`
}

SavedKeywordResult reports how the API handled one submitted keyword.

type SavedKeywordStatus added in v0.6.0 

type SavedKeywordStatus string

SavedKeywordStatus reports whether one item was created or skipped. 

const (
	SavedKeywordStatusCreated SavedKeywordStatus = "created"
	SavedKeywordStatusSkipped SavedKeywordStatus = "skipped"
)

type SavedKeywordText added in v0.6.0 

type SavedKeywordText string

SavedKeywordText is the compact string form accepted by CreateSavedKeywords.

type SavedKeywordTrendPoint added in v0.6.0 

type SavedKeywordTrendPoint struct {
	Month        int  `json:"month"`
	SearchVolume *int `json:"search_volume"`
	Year         int  `json:"year"`
}

SavedKeywordTrendPoint is one month of saved-keyword search-volume history.

type SavedView 

type SavedView struct {
	Config      SavedViewConfig `json:"config"`
	CreatedAt   time.Time       `json:"created_at"`
	CreatedByID *string         `json:"created_by_id"`
	ID          string          `json:"id"`
	Name        string          `json:"name"`
}

SavedView is a keyword saved view.

type SavedViewConfig 

type SavedViewConfig struct {
	Filters SavedViewFilters `json:"filters"`
	Search  string           `json:"search,omitempty"`
}

SavedViewConfig is the keyword grid state stored in a saved view.

type SavedViewDeleteResult 

type SavedViewDeleteResult struct {
	Deleted bool `json:"deleted"`
}

SavedViewDeleteResult is returned after deleting a saved view.

type SavedViewFilters 

type SavedViewFilters struct {
	Change   string                    `json:"change,omitempty"`
	Contains string                    `json:"contains,omitempty"`
	Country  string                    `json:"country,omitempty"`
	Device   string                    `json:"device,omitempty"`
	Position []SavedViewPositionBucket `json:"position,omitempty"`
	SERP     []string                  `json:"serp,omitempty"`
	Tags     []string                  `json:"tags,omitempty"`
	VolMax   int                       `json:"vol_max,omitempty"`
	VolMin   int                       `json:"vol_min,omitempty"`
	WrongURL bool                      `json:"wrong_url,omitempty"`
}

SavedViewFilters are keyword grid filters stored in a saved view.

type SavedViewPositionBucket 

type SavedViewPositionBucket string

SavedViewPositionBucket identifies a saved-view position bucket. 

const (
	SavedViewPositionTop3    SavedViewPositionBucket = "top3"
	SavedViewPositionTop10   SavedViewPositionBucket = "top10"
	SavedViewPosition11To50  SavedViewPositionBucket = "11-50"
	SavedViewPosition51To100 SavedViewPositionBucket = "51-100"
)

type SearchLocationsOptions 

type SearchLocationsOptions struct {
	Country string
	Limit   int
	Query   string
}

SearchLocationsOptions filters canonical keyword locations.

type SearchPerformanceQueryStat 

type SearchPerformanceQueryStat struct {
	Clicks      int     `json:"clicks"`
	CTR         float64 `json:"ctr"`
	Impressions int     `json:"impressions"`
	Page        *string `json:"page"`
	Position    float64 `json:"position"`
	Query       string  `json:"query"`
}

SearchPerformanceQueryStat is one live search-performance query row.

type SearchPerformanceQueryStatsResponse 

type SearchPerformanceQueryStatsResponse struct {
	Connection AnalyticsConnection          `json:"connection"`
	Rows       []SearchPerformanceQueryStat `json:"rows"`
}

SearchPerformanceQueryStatsResponse contains the selected connection and its rows.

type Signal 

type Signal struct {
	CreatedAt  time.Time      `json:"created_at"`
	HappenedAt time.Time      `json:"happened_at"`
	ID         string         `json:"id"`
	KeywordID  *string        `json:"keyword_id"`
	Payload    JSONValue      `json:"payload"`
	ProjectID  string         `json:"project_id"`
	PublicID   string         `json:"public_id"`
	Severity   SignalSeverity `json:"severity"`
	Source     SignalSource   `json:"source"`
	Type       string         `json:"type"`
	URL        *string        `json:"url"`
}

Signal is one ingested signal event.

type SignalSeverity 

type SignalSeverity string

SignalSeverity is the severity attached to a signal. 

const (
	SignalSeverityInfo     SignalSeverity = "info"
	SignalSeverityWarning  SignalSeverity = "warning"
	SignalSeverityCritical SignalSeverity = "critical"
)

type SignalSource 

type SignalSource string

SignalSource identifies where a signal originated. CreateSignal only accepts SignalSourceDeploy, SignalSourceCMS, and SignalSourceAPI; the remaining sources are emitted by Bisibility itself and appear in list responses and list filters. 

const (
	SignalSourceRankTracker        SignalSource = "rank_tracker"
	SignalSourceSearchAnalytics    SignalSource = "search_analytics"
	SignalSourceURLInspection      SignalSource = "url_inspection"
	SignalSourceSitemap            SignalSource = "sitemap"
	SignalSourceDeploy             SignalSource = "deploy"
	SignalSourceCMS                SignalSource = "cms"
	SignalSourceSearchEngineStatus SignalSource = "search_engine_status"
	SignalSourceManual             SignalSource = "manual"
	SignalSourceAPI                SignalSource = "api"
)

type SitemapMonitor 

type SitemapMonitor struct {
	Enabled        bool                          `json:"enabled"`
	ID             string                        `json:"id"`
	LatestSnapshot *SitemapMonitorLatestSnapshot `json:"latest_snapshot"`
	ProjectID      string                        `json:"project_id"`
	SitemapURL     *string                       `json:"sitemap_url"`
	Status         SitemapMonitorStatus          `json:"status"`
}

SitemapMonitor is the project sitemap monitor and latest snapshot state.

type SitemapMonitorLatestSnapshot 

type SitemapMonitorLatestSnapshot struct {
	FetchedAt  time.Time `json:"fetched_at"`
	SitemapURL string    `json:"sitemap_url"`
	URLCount   int       `json:"url_count"`
}

SitemapMonitorLatestSnapshot summarizes the most recent sitemap fetch.

type SitemapMonitorStatus 

type SitemapMonitorStatus string

SitemapMonitorStatus is the current sitemap monitoring state. 

const (
	SitemapMonitorStatusActive   SitemapMonitorStatus = "active"
	SitemapMonitorStatusDisabled SitemapMonitorStatus = "disabled"
	SitemapMonitorStatusPending  SitemapMonitorStatus = "pending"
)

type SuggestedCompetitor 

type SuggestedCompetitor struct {
	Domain   string `json:"domain"`
	Initials string `json:"initials"`
	Overlap  int    `json:"overlap"`
}

SuggestedCompetitor is a competitor suggestion returned in list metadata.

type TeamInvite 

type TeamInvite struct {
	Email        string        `json:"email"`
	ExpiresLabel string        `json:"expires_label"`
	ID           string        `json:"id"`
	InvitedLabel string        `json:"invited_label"`
	Role         string        `json:"role"`
	RoleValue    TeamRoleValue `json:"role_value"`
}

TeamInvite is one pending team invite returned by list endpoints.

type TeamInviteResendResult 

type TeamInviteResendResult struct {
	ExpiresAt  time.Time `json:"expires_at"`
	ID         string    `json:"id"`
	InviteLink string    `json:"invite_link"`
}

TeamInviteResendResult is returned after resending a project invite.

type TeamMember 

type TeamMember struct {
	Color     string        `json:"color"`
	Email     string        `json:"email"`
	ID        string        `json:"id"`
	Initials  string        `json:"initials"`
	Name      string        `json:"name"`
	Role      string        `json:"role"`
	RoleValue TeamRoleValue `json:"role_value"`
}

TeamMember is one project team member.

type TeamMemberMutationResult 

type TeamMemberMutationResult struct {
	ID string `json:"id"`
}

TeamMemberMutationResult is returned after removing a project member.

type TeamMemberRoleResult 

type TeamMemberRoleResult struct {
	ID   string        `json:"id"`
	Role TeamRoleValue `json:"role"`
}

TeamMemberRoleResult is returned after changing a project member's role.

type TeamRoleValue 

type TeamRoleValue string

TeamRoleValue is the API role value for project team access. 

const (
	TeamRoleAdmin   TeamRoleValue = "admin"
	TeamRoleAuditor TeamRoleValue = "auditor"
	TeamRoleMember  TeamRoleValue = "member"
	TeamRoleOwner   TeamRoleValue = "owner"
	TeamRoleViewer  TeamRoleValue = "viewer"
)

type TestProviderConnectionInput 

type TestProviderConnectionInput struct {
	Credentials *ProviderCredentialsInput `json:"credentials,omitempty"`
	Login       string                    `json:"login,omitempty"`
	Secret      string                    `json:"secret,omitempty"`
}

TestProviderConnectionInput tests provider credentials.

type TokenScope 

type TokenScope string

TokenScope is the tier granted to a personal access token. The effective tier per project is the minimum of the token scope and the user's membership role. 

const (
	TokenScopeRead  TokenScope = "read"
	TokenScopeWrite TokenScope = "write"
	TokenScopeAdmin TokenScope = "admin"
)

type TrackingScope 

type TrackingScope string

TrackingScope selects whether a project tracks ranks at country or city level. 

const (
	TrackingScopeCountry TrackingScope = "country"
	TrackingScopeCity    TrackingScope = "city"
)

type TrafficSyncRun 

type TrafficSyncRun struct {
	ConnectionID string               `json:"connection_id"`
	Error        *string              `json:"error,omitempty"`
	ErrorClass   *string              `json:"error_class,omitempty"`
	Provider     string               `json:"provider"`
	RowsFetched  int                  `json:"rows_fetched"`
	RowsMatched  int                  `json:"rows_matched"`
	RowsUpserted int                  `json:"rows_upserted"`
	Status       TrafficSyncRunStatus `json:"status"`
	Truncated    bool                 `json:"truncated"`
}

TrafficSyncRun is one provider connection's sync result.

type TrafficSyncRunStatus 

type TrafficSyncRunStatus string

TrafficSyncRunStatus reports one analytics connection sync outcome. 

const (
	TrafficSyncRunSucceededWithData TrafficSyncRunStatus = "succeeded_with_data"
	TrafficSyncRunSucceededEmpty    TrafficSyncRunStatus = "succeeded_empty"
	TrafficSyncRunDeferredRateLimit TrafficSyncRunStatus = "deferred_rate_limit"
	TrafficSyncRunFailed            TrafficSyncRunStatus = "failed"
	TrafficSyncRunNotApplicable     TrafficSyncRunStatus = "not_applicable"
)

type TrafficSyncSkipReason 

type TrafficSyncSkipReason string

TrafficSyncSkipReason explains why a provider did not run. 

const (
	TrafficSyncSkipNoCapability TrafficSyncSkipReason = "no_capability"
	TrafficSyncSkipRateLimited  TrafficSyncSkipReason = "rate_limited"
)

type TrafficSyncSkipped 

type TrafficSyncSkipped struct {
	Provider string                `json:"provider"`
	Reason   TrafficSyncSkipReason `json:"reason"`
}

TrafficSyncSkipped is one provider skipped during a project sync.

type TrafficSyncSummary 

type TrafficSyncSummary struct {
	Connections      int                  `json:"connections"`
	KeywordSnapshots int                  `json:"keyword_snapshots"`
	PageSnapshots    int                  `json:"page_snapshots"`
	ProjectID        string               `json:"project_id"`
	Runs             []TrafficSyncRun     `json:"runs"`
	Skipped          []TrafficSyncSkipped `json:"skipped"`
}

TrafficSyncSummary summarizes an on-demand project traffic sync.

type TriggeredAlert 

type TriggeredAlert struct {
	Action   string        `json:"action"`
	CTAs     []string      `json:"ctas"`
	Current  string        `json:"current"`
	Headline string        `json:"headline"`
	ID       string        `json:"id"`
	Keyword  string        `json:"keyword"`
	Previous string        `json:"previous"`
	Rule     string        `json:"rule"`
	Severity AlertSeverity `json:"severity"`
	Unread   bool          `json:"unread"`
	When     string        `json:"when"`
}

TriggeredAlert is one alert event returned by ListTriggeredAlerts.

type TriggeredAlertMuteResult 

type TriggeredAlertMuteResult struct {
	Muted        bool       `json:"muted"`
	SnoozedUntil *time.Time `json:"snoozed_until"`
}

TriggeredAlertMuteResult reports the alert snooze applied by MuteTriggeredAlert.

type TriggeredAlertsReadResult 

type TriggeredAlertsReadResult struct {
	Updated int `json:"updated"`
}

TriggeredAlertsReadResult reports how many firing alerts were marked read.

type UpdateAlertRuleInput 

type UpdateAlertRuleInput = CreateAlertRuleInput

UpdateAlertRuleInput updates an alert rule.

type UpdateKeywordInput 

type UpdateKeywordInput struct {
	City        *string
	Country     *string
	Device      *Device
	Frequency   *RankCheckFrequency
	Intent      NullableString
	Keyword     *string
	Location    *string
	LocationKey *string
	Schedule    *KeywordScheduleInput
	Tags        []string
	TargetURL   NullableString
	Topic       NullableString
}

UpdateKeywordInput updates keyword metadata. Use StringValue or NullString for TargetURL, Intent, and Topic; passing NullString clears the field.

func (UpdateKeywordInput) MarshalJSON 

func (in UpdateKeywordInput) MarshalJSON() ([]byte, error)

MarshalJSON includes only explicitly set update fields.

type UpdateMeInput 

type UpdateMeInput struct {
	Name string `json:"name"`
}

UpdateMeInput patches the authenticated user's profile.

type UpdateNotificationPreferencesInput 

type UpdateNotificationPreferencesInput struct {
	AlertEmail   *bool `json:"alert_email,omitempty"`
	AlertInApp   *bool `json:"alert_in_app,omitempty"`
	AlertSlack   *bool `json:"alert_slack,omitempty"`
	AlertWebhook *bool `json:"alert_webhook,omitempty"`
	CheckEmail   *bool `json:"check_email,omitempty"`
	CheckInApp   *bool `json:"check_in_app,omitempty"`
	ImportEmail  *bool `json:"import_email,omitempty"`
	ImportInApp  *bool `json:"import_in_app,omitempty"`
	InviteEmail  *bool `json:"invite_email,omitempty"`
	InviteInApp  *bool `json:"invite_in_app,omitempty"`
}

UpdateNotificationPreferencesInput patches notification preferences.

type UpdateProjectInput 

type UpdateProjectInput struct {
	Domain *string `json:"domain,omitempty"`
	Name   *string `json:"name,omitempty"`
}

UpdateProjectInput patches project metadata. At least one field is required.

type UpdateSitemapMonitorInput 

type UpdateSitemapMonitorInput struct {
	Enabled bool `json:"enabled"`
}

UpdateSitemapMonitorInput enables or disables sitemap monitoring.

type UpdateTeamMemberRoleInput 

type UpdateTeamMemberRoleInput struct {
	Role TeamRoleValue `json:"role"`
}

UpdateTeamMemberRoleInput changes a non-owner project member's role.

type UpdateWebhookInput 

type UpdateWebhookInput struct {
	Description *string `json:"description,omitempty"`
	Enabled     *bool   `json:"enabled,omitempty"`
	HMACSecret  string  `json:"hmac_secret,omitempty"`
	URL         string  `json:"url,omitempty"`
}

UpdateWebhookInput patches a project webhook. Omitted fields keep their current values.

type UpdatedNotificationPreferences 

type UpdatedNotificationPreferences struct {
	AlertEmail   bool   `json:"alert_email"`
	AlertInApp   bool   `json:"alert_in_app"`
	AlertSlack   bool   `json:"alert_slack"`
	AlertWebhook bool   `json:"alert_webhook"`
	CheckEmail   bool   `json:"check_email"`
	CheckInApp   bool   `json:"check_in_app"`
	ImportEmail  bool   `json:"import_email"`
	ImportInApp  bool   `json:"import_in_app"`
	InviteEmail  bool   `json:"invite_email"`
	InviteInApp  bool   `json:"invite_in_app"`
	ProjectID    string `json:"project_id"`
}

UpdatedNotificationPreferences is returned after a preferences patch.

type Webhook 

type Webhook struct {
	CreatedAt      time.Time  `json:"created_at"`
	Description    *string    `json:"description"`
	Enabled        bool       `json:"enabled"`
	ID             string     `json:"id"`
	LastDeliveryAt *time.Time `json:"last_delivery_at"`
	UpdatedAt      time.Time  `json:"updated_at"`
	URL            string     `json:"url"`
}

Webhook is one project webhook. The HMAC secret is write-only and never returned by the API.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.