jsonseo

package module
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Sep 23, 2026 License: MIT Imports: 14 Imported by: 0

README

JSON SEO Go SDK

Официальный Go-клиент JSON SEO API: выдача Яндекса, Google и Bing, картинки и видео, поисковые подсказки, Яндекс Вордстат, прогноз показов Директа и геолокация по IP.

  • Работает на Go 1.21 и выше.
  • Без зависимостей: только стандартная библиотека.
  • Контекст в каждом методе: отмена и дедлайн работают как положено.
  • Двадцать один метод сервиса.
  • Три попытки на запрос по умолчанию: если сервис затупил, SDK сходит ещё раз сам.

Установка

go get github.com/jsonseo/go-sdk

Ключ берётся в личном кабинете.

Быстрый старт

package main

import (
	"context"
	"fmt"
	"log"

	jsonseo "github.com/jsonseo/go-sdk"
)

func main() {
	client, err := jsonseo.New("YOUR_KEY")
	if err != nil {
		log.Fatal(err)
	}

	serp, err := client.Yandex(context.Background(), "купить ноутбук", jsonseo.Params{
		"region": 213,
	})
	if err != nil {
		log.Fatal(err)
	}

	for position, result := range serp.Results {
		fmt.Printf("%d. %s — %s\n", position+1, result.Domain, result.Title)
	}
}

Второй аргумент — основной параметр метода, остальное передаётся набором Params. Он необязателен:

serp, err := client.Yandex(ctx, "купить ноутбук")
geo, err := client.Geoip(ctx, "77.88.55.242")
balance, err := client.Balance(ctx)

Примеры запросов

Позиции сайта в Яндексе

break_domain останавливает сбор на нужном домене — платить за страницы ниже найденной позиции незачем.

serp, err := client.Yandex(ctx, "ремонт айфона", jsonseo.Params{
	"region":       213, // Москва
	"pages":        10,  // до 100 позиций
	"break_domain": "example.com",
})
if err != nil {
	log.Fatal(err)
}

for index, result := range serp.Results {
	if strings.HasSuffix(result.Domain, "example.com") {
		fmt.Println("Позиция:", index+1)

		break
	}
}

fmt.Println("Собрано страниц:", serp.Pages)
fmt.Println("Нашлось всего:", serp.FoundHuman)

serp.Found — указатель: nil означает «разобрать не удалось», а не ноль.

Выдача Google по нужному городу

Регион задаётся числовым ID из справочника — сервис сам соберёт uule и подставит gl.

regions, err := client.GoogleRegions(ctx, "Казань")
if err != nil {
	log.Fatal(err)
}

serp, err := client.Google(ctx, "заказать пиццу", jsonseo.Params{
	"region": regions.Regions[0].ID,
	"hl":     "ru",
	"device": "desktop",
	"pages":  2,
})

Если Google схлопнул часть результатов как «очень похожие», причина придёт в serp.FilterDescription, а вернуть их можно параметром filter:

serp, err := client.Google(ctx, "заказать пиццу", jsonseo.Params{"filter": 0})

Выдача Bing

serp, err := client.Bing(ctx, "buy a laptop", jsonseo.Params{
	"mkt":   "en-US",
	"pages": 2,
})

fmt.Println(serp.Mkt, serp.Lang) // фактический рынок и язык

Реклама на странице выдачи

Приходит отдельным срезом, органика не меняется. Стоит +0.01 ₽ за страницу, на которой реклама нашлась.

serp, err := client.Yandex(ctx, "пластиковые окна", jsonseo.Params{
	"region": 213,
	"ads":    true,
})

for _, ad := range serp.Ads {
	fmt.Printf("%s #%d — %s\n", ad.Block, ad.Position, ad.Domain)
	fmt.Println("  ", ad.Title)
}

Block — где стоял блок: top до органики, bottom после неё, inline между результатами. Пустой непустой срез значит «рекламу просили, но её не было», а nil — «не просили».

Ответ нейросети над выдачей

serp, err := client.Yandex(ctx, "чем отличается osb от фанеры", jsonseo.Params{"ai": true})

if serp.AiAnswer != nil {
	fmt.Println(serp.AiAnswer.Markdown)

	for _, source := range serp.AiAnswer.Sources {
		fmt.Printf("[%d] %s\n", source.ID, source.Domain)
	}
}

Стоит +0.01 ₽ и только когда ответ есть: если поисковик его не показал, запрос обойдётся в обычную цену. Доступен только с первой страницы.

Картинки

images, err := client.YandexImages(ctx, "скандинавский интерьер", jsonseo.Params{
	"orientation": "horizontal",
	"size":        "large",
	"format":      "jpg",
	"pages":       2,
})

for _, image := range images.Results {
	fmt.Printf("%d×%d %s\n", image.Width, image.Height, image.URL)
	fmt.Println("   источник:", image.SourceURL)
}

Те же параметры работают у GoogleImages() и BingImages() — SDK переводит общий фильтр в родной параметр движка. Если у поисковика такого значения нет, придёт ErrValidation с указанием, чем заменить.

Видео

videos, err := client.GoogleVideo(ctx, "как заменить ремень грм", jsonseo.Params{
	"duration": "long",
	"hl":       "ru",
})

for _, video := range videos.Results {
	fmt.Printf("%s — %s\n", video.Title, video.DurationText)
	fmt.Printf("   %s (%s)\n", video.URL, video.Provider)
}

Duration — указатель на секунды, и nil означает «длина неизвестна», а не ноль: у прямых эфиров вместо подписи стоит LIVE. Отбор вида *video.Duration < 600 без проверки на nil уронит программу — ориентируйтесь на DurationText, он на месте всегда.

Поисковые подсказки

suggest, err := client.YandexSuggest(ctx, "купить кв", jsonseo.Params{"region": 213})

fmt.Println(suggest.Results)
// [купить квартиру в москве купить квартиру в новостройке ...]

Есть у всех трёх поисковиков: YandexSuggest(), GoogleSuggest(), BingSuggest().

Справочник регионов

regions, err := client.YandexRegions(ctx, "Казань")

for _, region := range regions.Regions {
	fmt.Printf("%d — %s (%s)\n", region.ID, region.Name, region.Subname)
}
// 43 — Казань (Республика Татарстан)

Бесплатно, но ключ нужен: по нему считается лимит запросов в минуту. У GoogleRegions() в ответе дополнительно приходит готовая строка UULE.

Вордстат: частота запроса

frequency, err := client.WordstatFrequency(ctx, "ремонт айфона", jsonseo.Params{
	"kind":   "exact", // точная частотность: "!ремонт !айфона"
	"region": 213,
})

fmt.Println(frequency.Results.TotalValue) // 27356

Вид частотности задаётся параметром kind, кавычки и операторы расставит сервис — фразу передавайте как есть:

kind Что считает
base Базовая: фраза как есть
phrase Фразовая: "фраза"
exact Точная: "!слово !слово" — для прогноза трафика берут её
superexact Сверхточная: "[!слово !слово]"

Вордстат: расширение семантики

wordstat, err := client.Wordstat(ctx, "ремонт айфона", jsonseo.Params{"region": []int{213, 2}})

for _, phrase := range wordstat.Results.Popular {
	fmt.Println(phrase.Value, phrase.Text)
}

for _, phrase := range wordstat.Results.Associations {
	fmt.Println(phrase.Value, phrase.Text)
}

Popular — что ищут вместе с фразой, Associations — соседняя семантика.

Вордстат: сезонность

graph, err := client.WordstatGraph(ctx, "купить ёлку", jsonseo.Params{"graph_type": "month"})

for _, point := range graph.Results.Graph {
	fmt.Println(point.Text, point.Absolute)
}
// июнь 2026 9042
// июль 2026 11780

month и week отдают историю с 2018 года, day — последние 60 дней.

Вордстат: география спроса

geo, err := client.WordstatMap(ctx, "купить ноутбук", jsonseo.Params{"map_type": "regions"})

for _, row := range geo.Results.Rows {
	fmt.Println(row.Text, row.Absolute, "индекс", row.Popularity)
}

Popularity — affinity-индекс: 100 означает средний по стране интерес, выше — повышенный. В каждой строке приходит RegionID (указатель, nil при неоднозначном названии), его можно сразу подставить в region других методов.

Прогноз показов Яндекс Директа

Рекламный кабинет не нужен. Список фраз передаётся срезом — SDK склеит его сам.

forecast, err := client.Direct(ctx,
	[]string{"ремонт айфона", "замена экрана iphone", `"ремонт айфона"`},
	jsonseo.Params{"region": 213, "period": "month"},
)

for _, row := range forecast.Results {
	fmt.Printf("%s: %d показов\n", row.Phrase, row.Shows)

	for place, bid := range row.Positions {
		fmt.Printf("   %s: ставка %.2f ₽, бюджет %.2f ₽, кликов %d\n",
			place, bid.Bid, bid.Budget, bid.Clicks)
	}
}

Вид частотности задаётся операторами прямо во фразе: ремонт айфона — базовая, "ремонт айфона" — фразовая, "!ремонт !айфона" — точная.

Стоимость — 0.01 ₽ за пачку до 4000 символов, это около 150 обычных фраз. За один запрос принимается до 1000 фраз, на аккаунт — не больше 100 запросов в час.

Геолокация по IP

geo, err := client.Geoip(ctx, "77.88.55.242")

fmt.Println(geo.Country.Name, geo.Region.Name)
fmt.Println(geo.Latitude, geo.Longitude)

ID региона тот же, что у Яндекса, — его можно сразу подставить в region методов выдачи и Вордстата:

serp, err := client.Yandex(ctx, "доставка пиццы", jsonseo.Params{"region": geo.Region.ID})

Баланс

balance, err := client.Balance(ctx)

fmt.Println(balance.Balance, balance.Currency) // 123.45 RUB

Справочник методов

Метод Путь API Что делает
Yandex() /yandex Органическая выдача Яндекса
YandexSuggest() /yandex/suggest Поисковые подсказки
YandexRegions() /yandex/regions Справочник регионов, бесплатно
YandexImages() /yandex/images Поиск по картинкам
YandexVideo() /yandex/video Поиск по видео
Google() /google Органическая выдача Google
GoogleSuggest() /google/suggest Подсказки
GoogleRegions() /google/regions Регионы и готовый uule, бесплатно
GoogleImages() /google/images Поиск по картинкам
GoogleVideo() /google/video Поиск по видео
Bing() /bing Органическая выдача Bing
BingSuggest() /bing/suggest Подсказки
BingImages() /bing/images Поиск по картинкам
BingVideo() /bing/video Поиск по видео
Wordstat() /wordstat Популярные и похожие запросы
WordstatFrequency() /wordstat/frequency Частота запроса одним числом
WordstatGraph() /wordstat/graph Динамика по месяцам, неделям, дням
WordstatMap() /wordstat/map География показов
Direct() /direct Прогноз показов Яндекс Директа
Geoip() /geoip Геолокация по IPv4, бесплатно
Balance() /balance Остаток на счёте, бесплатно

Полный список параметров каждого метода — в документации.

Появился метод, которого ещё нет в SDK? Его можно вызвать напрямую:

var result MyType
err := client.Call(ctx, "новый/метод", jsonseo.Params{"параметр": "значение"}, &result)

body, err := client.CallRaw(ctx, "новый/метод", jsonseo.Params{"параметр": "значение"})

Как SDK помогает с параметрами

Списки передаются срезами. Фразы для Директа склеиваются переводом строки, остальные списки — запятой:

client.Direct(ctx, []string{"ремонт айфона", "ремонт телефона"})
client.Wordstat(ctx, "ремонт", jsonseo.Params{
	"region": []int{213, 2},
	"device": []string{"desktop", "phone"},
})

Флаги принимаются флагами. true и false уезжают как 1 и 0:

client.Yandex(ctx, "купить ноутбук", jsonseo.Params{"ai": true, "ads": true})

nil и пустой срез не отправляются. Необязательный параметр, который вы ещё не посчитали, можно не вычищать из набора руками.

Родные параметры поисковиков проходят насквозь. Вертикали принимают не только общие фильтры, но и tbs у Google, isize у Яндекса, qft у Bing.

Ошибки

Отказы сервиса приезжают как *APIError и сопоставляются с сигнальными ошибками через errors.Is.

Сигнал Статус Когда
ErrValidation 422 Параметры не приняты. Errors — сообщения по полям
ErrUnauthorized 403, 401 Ключ не передан или недействителен
ErrPaymentRequired 402 На счёте не хватает средств
ErrRateLimited 429 Превышен лимит частоты
ErrServiceUnavailable 503 Выдачу получить не вышло. Деньги не списаны
Сигнал Когда
ErrNetwork До сервиса не достучались: сеть, DNS, TLS
ErrTimeout Ответа не дождались
ErrIncompleteResponse Соединение оборвалось посреди тела
ErrParse Ответ пришёл, но не разобрался как JSON
ErrInvalidArgument SDK забраковал аргументы, запрос не отправлялся 
serp, err := client.Yandex(ctx, "купить ноутбук", jsonseo.Params{"pages": 50})

switch {
case errors.Is(err, jsonseo.ErrValidation):
	var apiErr *jsonseo.APIError
	errors.As(err, &apiErr)

	for field, messages := range apiErr.Errors {
		fmt.Println(field, strings.Join(messages, ", "))
	}
case errors.Is(err, jsonseo.ErrPaymentRequired):
	balance, _ := client.Balance(ctx)
	fmt.Println("Баланс кончился:", balance.Balance)
case errors.Is(err, jsonseo.ErrRateLimited):
	var apiErr *jsonseo.APIError
	errors.As(err, &apiErr)

	fmt.Println("Вернуться через", apiErr.RetryAfter, "с")
case err != nil:
	log.Fatal(err)
}

У *APIError есть Status, Message, Body, разобранный Payload и RetryAfter — срок, который назвал сервис, если он его назвал.

Отмену и дедлайн вызывающего SDK отдаёт как есть: errors.Is(err, context.Canceled) и errors.Is(err, context.DeadlineExceeded) работают.

Повторы

У каждого запроса три попытки по умолчанию: одна основная и две повторных. Если сервис затупил и выдачу собрать не вышло (503), SDK сам сходит ещё дважды, и обычно этого хватает. WithAttempts(1) отключает повторы совсем.

429, 5xx и обрывы связи повторяются автоматически — это ровно те отказы, за которые сервис денег не берёт. Отказы по ключу, балансу и параметрам не повторяются: сами они не изменятся.

Таймаут и оборвавшееся посреди тела соединение не повторяются, и это намеренно: работу на стороне сервиса обрыв у клиента не отменяет — выдача будет собрана и оплачена, а повтор стоил бы ещё раз. Если ответ не успевает прийти, поднимайте WithTimeout, а не WithAttempts.

Пауза между попытками удваивается и разбавляется случайной добавкой. Если сервис прислал Retry-After, SDK не вернётся раньше названного срока. Когда сервис просит ждать дольше WithMaxRetryDelay, SDK не ждёт вовсе, а отдаёт ошибку с RetryAfter — решение остаётся за вами.

Пауза прерывается контекстом: отмена срабатывает сразу, а не в конце ожидания.

Настройки клиента

client, err := jsonseo.New("YOUR_KEY",
	jsonseo.WithBaseURL("https://jsonseo.ru/api"),   // адрес API
	jsonseo.WithTimeout(5*time.Minute),              // сколько ждать ответа на попытку
	jsonseo.WithAttempts(3),                         // всего попыток, вместе с первой
	jsonseo.WithRetryDelay(time.Second),             // стартовая пауза между попытками
	jsonseo.WithMaxRetryDelay(30*time.Second),       // потолок паузы
	jsonseo.WithAuthInQuery(),                       // ключ в параметре key вместо заголовка
	jsonseo.WithUserAgent("мой-проект/1.0"),
	jsonseo.WithHTTPClient(myHTTPClient),            // свой http.Client: прокси, транспорт, тесты
)

Таймаут по умолчанию намеренно большой: многостраничный запрос выдачи собирается минутами, и обрыв на стороне клиента не отменяет запрос на стороне сервиса — деньги за него уже списаны. Считается он на каждую попытку отдельно, а не на весь вызов; общий бюджет задавайте контекстом:

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()

serp, err := client.Yandex(ctx, "купить ноутбук")

Ключ по умолчанию едет в заголовке Authorization: Bearer, а не в адресе: так он не оседает в логах прокси и серверов.

Разработка

go test ./...
go vet ./...

Тесты идут без внешней сети: поднимается свой httptest-сервер на loopback.

Лицензия

MIT.

Documentation

Overview

Package jsonseo — официальный Go SDK для JSON SEO API: выдача Яндекса, Google и Bing, картинки и видео, подсказки, Вордстат, прогноз Директа и геолокация по IP. 

client, err := jsonseo.New("YOUR_KEY")
serp, err := client.Yandex(ctx, "купить ноутбук", jsonseo.Params{"region": 213})

Index

Constants

View Source 
const DefaultBaseURL = "https://jsonseo.ru/api"

DefaultBaseURL — адрес API по умолчанию.

View Source 
const Version = "1.0.2"

Version — версия SDK, уезжает в User-Agent.

Variables

View Source 
var (
	// ErrUnauthorized — 403 или 401: ключ не передан или недействителен.
	ErrUnauthorized = errors.New("jsonseo: ключ не передан или недействителен")
	// ErrPaymentRequired — 402: на счёте не хватает средств.
	ErrPaymentRequired = errors.New("jsonseo: на счёте не хватает средств")
	// ErrValidation — 422: параметры не приняты. Деньги не списываются.
	ErrValidation = errors.New("jsonseo: параметры запроса не приняты")
	// ErrRateLimited — 429: превышен лимит частоты.
	ErrRateLimited = errors.New("jsonseo: превышен лимит частоты")
	// ErrServiceUnavailable — 503: выдачу получить не вышло, деньги не списаны.
	ErrServiceUnavailable = errors.New("jsonseo: выдачу получить не вышло")
	// ErrTimeout — ответа не дождались. Автоматически не повторяется.
	ErrTimeout = errors.New("jsonseo: ответа не дождались")
	// ErrIncompleteResponse — пришло меньше, чем обещал сервис.
	ErrIncompleteResponse = errors.New("jsonseo: ответ пришёл не целиком")
	// ErrNetwork — до сервиса не достучались: сеть, DNS, TLS.
	ErrNetwork = errors.New("jsonseo: запрос не удался")
	// ErrParse — ответ пришёл, но не разобрался как JSON.
	ErrParse = errors.New("jsonseo: ответ не разобрался как JSON")
	// ErrInvalidArgument — SDK забраковал аргументы, запрос не отправлялся.
	ErrInvalidArgument = errors.New("jsonseo: неверный аргумент")
)

Сигнальные ошибки для errors.Is. Отказы сервиса приезжают как *APIError, который сам сопоставляется с нужной из них по HTTP-статусу.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	// Status — HTTP-статус ответа.
	Status int
	// Message — сообщение сервиса.
	Message string
	// Body — тело ответа как есть.
	Body string
	// Payload — разобранный JSON ответа. Пустой, если тело не разобралось.
	Payload map[string]any
	// Errors — ошибки по именам параметров, приходят с 422.
	Errors map[string][]string
	// RetryAfter — через сколько секунд вернуться. 0, если срок не назван.
	RetryAfter int
}

APIError — сервис ответил отказом. Тело сохраняется целиком.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Fields 

func (e *APIError) Fields() []string

Fields — забракованные параметры, если отказ пришёл с 422. Порядок обхода map случаен, поэтому имена сортируются: иначе лог и сравнение плясали бы от запуска к запуску.

func (*APIError) Is 

func (e *APIError) Is(target error) bool

Is сопоставляет отказ с сигнальной ошибкой по статусу, чтобы работал errors.Is(err, jsonseo.ErrPaymentRequired). 

type Ad struct {
	// Block — top до органики, bottom после неё, inline между результатами.
	Block string `json:"block"`
	// Position — место среди объявлений своего блока, с единицы.
	Position int `json:"position"`
	// Page — страница выдачи: нумерация с нуля и абсолютная.
	Page        int          `json:"page"`
	Domain      string       `json:"domain"`
	URL         string       `json:"url,omitempty"`
	DisplayURL  string       `json:"displayUrl,omitempty"`
	Title       string       `json:"title,omitempty"`
	Description string       `json:"description,omitempty"`
	Label       string       `json:"label,omitempty"`
	Format      string       `json:"format,omitempty"`
	Group       int          `json:"group,omitempty"`
	Sitelinks   []AdSitelink `json:"sitelinks,omitempty"`
}

Ad — рекламное объявление со страницы выдачи. 

type AdSitelink struct {
	Title       string `json:"title"`
	URL         string `json:"url,omitempty"`
	Description string `json:"description,omitempty"`
}

AdSitelink — быстрая ссылка под текстом объявления.

type AiAnswer 

type AiAnswer struct {
	Markdown string           `json:"markdown"`
	Sources  []AiAnswerSource `json:"sources,omitempty"`
	// FollowUps — только Яндекс: уточняющие вопросы под ответом.
	FollowUps []string `json:"followUps,omitempty"`
}

AiAnswer — блок нейросети над выдачей: Алиса AI, AI Overview, Copilot.

type AiAnswerSource 

type AiAnswerSource struct {
	// ID — номер источника: им подписаны сноски у Яндекса и Bing.
	ID          int    `json:"id"`
	URL         string `json:"url"`
	Domain      string `json:"domain"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	// Citations — сколько сносок ведёт на источник. Только Яндекс и Bing.
	Citations int `json:"citations,omitempty"`
}

AiAnswerSource — источник, на который опирается ответ нейросети.

type BalanceResponse 

type BalanceResponse struct {
	Balance  float64 `json:"balance"`
	Currency string  `json:"currency"`
}

BalanceResponse — остаток на счёте.

type Client 

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

Client — клиент JSON SEO API. Безопасен для одновременного использования.

func New 

func New(apiKey string, opts ...Option) (*Client, error)

New создаёт клиент. Ключ берётся в личном кабинете на jsonseo.ru.

func (*Client) Balance 

func (c *Client) Balance(ctx context.Context) (*BalanceResponse, error)

Balance — текущий баланс. Бесплатно, нужен ключ.

func (*Client) Bing 

func (c *Client) Bing(ctx context.Context, query string, params ...Params) (*SearchResponse, error)

Bing — органическая выдача bing.com: без локации — Россия. 0.01 ₽ за страницу.

func (*Client) BingImages 

func (c *Client) BingImages(ctx context.Context, query string, params ...Params) (*ImagesResponse, error)

BingImages — картинки Bing: count карточек (по умолчанию 35), дальше 700-й Bing не листает.

func (*Client) BingSuggest 

func (c *Client) BingSuggest(ctx context.Context, query string, params ...Params) (*SuggestResponse, error)

BingSuggest — подсказки Bing. 0.01 ₽ за запрос.

func (*Client) BingVideo 

func (c *Client) BingVideo(ctx context.Context, query string, params ...Params) (*VideoResponse, error)

BingVideo — видео Bing: count карточек на страницу, по умолчанию 105.

func (*Client) Call 

func (c *Client) Call(ctx context.Context, path string, params Params, out any) error

Call — произвольный метод API, если в сервисе появился новый. Ответ разбирается в out.

func (*Client) CallRaw 

func (c *Client) CallRaw(ctx context.Context, path string, params Params) (string, error)

CallRaw — то же, но ответ возвращается строкой без разбора.

func (*Client) Direct 

func (c *Client) Direct(ctx context.Context, phrases []string, params ...Params) (*DirectResponse, error)

Direct — прогноз показов Директа со ставками и бюджетом. Кабинет не нужен.

0.01 ₽ за пачку до 4000 символов (около 150 фраз). До 1000 фраз за запрос, 100 запросов в час. Вид частотности задаётся операторами во фразе: "ремонт айфона" — фразовая, "!ремонт !айфона" — точная.

func (*Client) Geoip 

func (c *Client) Geoip(ctx context.Context, ip string, params ...Params) (*GeoipResponse, error)

Geoip — страна, регион и координаты по IPv4. Бесплатно, нужен ключ.

func (*Client) Google 

func (c *Client) Google(ctx context.Context, query string, params ...Params) (*SearchResponse, error)

Google — органическая выдача google.com: мобильная. 0.01 ₽ за страницу.

func (*Client) GoogleImages 

func (c *Client) GoogleImages(ctx context.Context, query string, params ...Params) (*ImagesResponse, error)

GoogleImages — картинки Google: 100 карточек на страницу. 0.01 ₽ за страницу.

func (*Client) GoogleRegions 

func (c *Client) GoogleRegions(ctx context.Context, name string, params ...Params) (*GoogleRegionsResponse, error)

GoogleRegions — ID региона Google по названию и готовый uule. Бесплатно, нужен ключ.

func (*Client) GoogleSuggest 

func (c *Client) GoogleSuggest(ctx context.Context, query string, params ...Params) (*SuggestResponse, error)

GoogleSuggest — подсказки Google: до ~15 фраз. 0.01 ₽ за запрос.

func (*Client) GoogleVideo 

func (c *Client) GoogleVideo(ctx context.Context, query string, params ...Params) (*VideoResponse, error)

GoogleVideo — видео Google: 10 карточек на страницу. 0.01 ₽ за страницу.

func (*Client) Wordstat 

func (c *Client) Wordstat(ctx context.Context, text string, params ...Params) (*WordstatResponse, error)

Wordstat — популярные и похожие запросы. 0.01 ₽ за запрос.

func (*Client) WordstatFrequency 

func (c *Client) WordstatFrequency(ctx context.Context, text string, params ...Params) (*WordstatFrequencyResponse, error)

WordstatFrequency — частота запроса одним числом: Results.TotalValue. 0.01 ₽ за запрос.

func (*Client) WordstatGraph 

func (c *Client) WordstatGraph(ctx context.Context, text string, params ...Params) (*WordstatGraphResponse, error)

WordstatGraph — динамика показов: month и week с 2018 года, day — последние 60 дней. 0.01 ₽ за запрос.

func (*Client) WordstatMap 

func (c *Client) WordstatMap(ctx context.Context, text string, params ...Params) (*WordstatMapResponse, error)

WordstatMap — показы по регионам и городам. Popularity — affinity-индекс: 100 означает средний интерес. 0.01 ₽ за запрос.

func (*Client) Yandex 

func (c *Client) Yandex(ctx context.Context, text string, params ...Params) (*SearchResponse, error)

Yandex — органическая выдача Яндекса: мобильная, регион 213. 0.01 ₽ за страницу.

func (*Client) YandexImages 

func (c *Client) YandexImages(ctx context.Context, query string, params ...Params) (*ImagesResponse, error)

YandexImages — картинки Яндекса: 20 карточек на страницу. 0.01 ₽ за страницу.

func (*Client) YandexRegions 

func (c *Client) YandexRegions(ctx context.Context, name string, params ...Params) (*YandexRegionsResponse, error)

YandexRegions — код региона (lr) по названию города или области. Бесплатно, нужен ключ.

func (*Client) YandexSuggest 

func (c *Client) YandexSuggest(ctx context.Context, text string, params ...Params) (*SuggestResponse, error)

YandexSuggest — подсказки Яндекса: до 50 фраз с учётом региона. 0.01 ₽ за запрос.

func (*Client) YandexVideo 

func (c *Client) YandexVideo(ctx context.Context, query string, params ...Params) (*VideoResponse, error)

YandexVideo — видео Яндекса: 20 карточек на страницу. 0.01 ₽ за страницу.

type DirectForecast 

type DirectForecast struct {
	Phrase string `json:"phrase"`
	Shows  int    `json:"shows"`
	// Positions — места аукциона: набор задаёт сам Директ.
	Positions map[string]DirectPosition `json:"positions"`
}

DirectForecast — прогноз по одной фразе.

type DirectPosition 

type DirectPosition struct {
	Bid    float64 `json:"bid"`
	Budget float64 `json:"budget"`
	Clicks int     `json:"clicks"`
	CTR    float64 `json:"ctr"`
	Shows  int     `json:"shows"`
}

DirectPosition — прогноз по одному месту аукциона.

type DirectResponse 

type DirectResponse struct {
	Geo    int    `json:"geo"`
	Period string `json:"period"`
	// Batches — на сколько пачек разбит список: по ним считается стоимость.
	Batches   int              `json:"batches"`
	Processed int              `json:"processed"`
	Results   []DirectForecast `json:"results"`
	Errors    []string         `json:"errors"`
}

DirectResponse — прогноз показов Яндекс Директа.

type GeoipResponse 

type GeoipResponse struct {
	IP        string  `json:"ip"`
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
	Region    struct {
		// ID тот же, что у Яндекса: годится для параметра region.
		ID   int    `json:"id"`
		Name string `json:"name"`
	} `json:"region"`
	Country struct {
		ID      int    `json:"id"`
		Name    string `json:"name"`
		ISOName string `json:"iso_name"`
	} `json:"country"`
}

GeoipResponse — геолокация по IP.

type GoogleRegion 

type GoogleRegion struct {
	ID            int     `json:"id"`
	Name          string  `json:"name"`
	Subname       string  `json:"subname"`
	Type          string  `json:"type"`
	TypeName      string  `json:"type_name"`
	CanonicalName string  `json:"canonical_name"`
	UULE          string  `json:"uule"`
	Lat           float64 `json:"lat"`
	Lon           float64 `json:"lon"`
}

GoogleRegion — регион Google: вместе с ID приходит готовый uule.

type GoogleRegionsResponse 

type GoogleRegionsResponse struct {
	Name    string         `json:"name"`
	Lang    string         `json:"lang"`
	Regions []GoogleRegion `json:"regions"`
}

GoogleRegionsResponse — ответ справочника регионов Google.

type ImageResult 

type ImageResult struct {
	URL       string `json:"url"`
	Title     string `json:"title"`
	Domain    string `json:"domain"`
	SourceURL string `json:"sourceUrl"`
	Thumbnail string `json:"thumbnail,omitempty"`
	// Width и Height — размер оригинала. Ноль означает «поисковик не назвал».
	Width           int `json:"width,omitempty"`
	Height          int `json:"height,omitempty"`
	ThumbnailWidth  int `json:"thumbnailWidth,omitempty"`
	ThumbnailHeight int `json:"thumbnailHeight,omitempty"`
	Bytes           int `json:"bytes,omitempty"`
}

ImageResult — карточка картинки: первые четыре поля есть всегда.

type ImagesResponse 

type ImagesResponse struct {
	Pages     int           `json:"pages"`
	Exhausted bool          `json:"exhausted"`
	Query     string        `json:"query"`
	URL       string        `json:"url,omitempty"`
	Results   []ImageResult `json:"results"`
	Ads       []Ad          `json:"ads,omitempty"`
}

ImagesResponse — ответ поиска по картинкам.

type Option 

type Option func(*Client) error

Option настраивает клиент.

func WithAttempts 

func WithAttempts(attempts int) Option

WithAttempts задаёт общее число попыток, включая первую. По умолчанию три.

func WithAuthInQuery 

func WithAuthInQuery() Option

WithAuthInQuery переносит ключ из заголовка в параметр key — там, где заголовки до API не доходят.

func WithBaseURL 

func WithBaseURL(url string) Option

WithBaseURL задаёт адрес API.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient подставляет свой http.Client — для прокси, своего транспорта или тестов.

func WithMaxRetryDelay 

func WithMaxRetryDelay(delay time.Duration) Option

WithMaxRetryDelay задаёт потолок паузы. Если сервис просит ждать дольше, повторов не будет вовсе — в том числе при нуле: он означает «не ждать ни секунды», а не «без потолка».

func WithRetryDelay 

func WithRetryDelay(delay time.Duration) Option

WithRetryDelay задаёт стартовую паузу между попытками.

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout задаёт, сколько ждать ответа на одну попытку.

По умолчанию пять минут: многостраничная выдача идёт минутами, и оборванный запрос всё равно будет досчитан и оплачен.

func WithUserAgent 

func WithUserAgent(agent string) Option

WithUserAgent задаёт свою подпись клиента.

type Params 

type Params map[string]any

Params — необязательные параметры метода.

Запись открыта не для удобства: вертикали принимают и родные параметры поисковиков — tbs, isize, qft, — перечислить которые нельзя, они меняются вместе с поисковиками. 

client.Yandex(ctx, "купить ноутбук", jsonseo.Params{"region": 213, "ads": true})

type ParseError 

type ParseError struct {
	Body string
	Err  error
}

ParseError — успех, но тело не разобралось как JSON. Тело сохраняется: страница уже оплачена, и достать из неё данные руками лучше, чем ничего.

func (*ParseError) Error 

func (e *ParseError) Error() string

func (*ParseError) Is 

func (e *ParseError) Is(target error) bool

func (*ParseError) Unwrap 

func (e *ParseError) Unwrap() error

type SearchResponse 

type SearchResponse struct {
	// Pages — сколько страниц получено: ровно за них и списано.
	Pages int `json:"pages"`
	// Exhausted — выдача закончилась, повторять с большим pages незачем.
	Exhausted bool `json:"exhausted"`
	// BreakDomainHit — поиск остановлен доменом из break_domain.
	BreakDomainHit bool   `json:"breakDomainHit"`
	Query          string `json:"query"`
	RawQuery       string `json:"rawQuery"`
	Region         string `json:"region,omitempty"`
	// FilterDescription — только Google: почему часть результатов скрыта.
	FilterDescription string `json:"filter_description,omitempty"`
	// Found — только Яндекс: сколько нашлось, округлённо самим поисковиком.
	// nil, если разобрать не удалось.
	Found      *int64 `json:"found,omitempty"`
	FoundHuman string `json:"found_human,omitempty"`
	// Mkt и Lang — только Bing: фактические рынок и язык выдачи.
	Mkt  string `json:"mkt,omitempty"`
	Lang string `json:"lang,omitempty"`
	// Lr — только Яндекс: регион, в котором выполнен поиск.
	Lr      int            `json:"lr,omitempty"`
	URL     string         `json:"url,omitempty"`
	Results []SearchResult `json:"results"`
	// AiAnswer приходит только при ai=1 и только если поисковик его показал.
	AiAnswer *AiAnswer `json:"aiAnswer,omitempty"`
	// Ads приходит только при ads=1. Пустой, но не nil срез значит, что
	// рекламу просили, а её не было; nil — что не просили.
	Ads []Ad `json:"ads,omitempty"`
}

SearchResponse — ответ органической выдачи, общий для трёх поисковиков.

type SearchResult 

type SearchResult struct {
	URL         string `json:"url"`
	Domain      string `json:"domain"`
	Title       string `json:"title"`
	Passage     string `json:"passage"`
	Breadcrumbs string `json:"breadcrumbs,omitempty"`
	// Mime — тип документа: pdf, doc, xls. Пусто у обычных страниц.
	Mime     string `json:"mime,omitempty"`
	MimeType string `json:"mime_type,omitempty"`
}

SearchResult — органический результат выдачи.

type SuggestResponse 

type SuggestResponse struct {
	Query   string   `json:"query"`
	Results []string `json:"results"`
	// Lr — только Яндекс: регион, в котором собраны подсказки.
	Lr string `json:"lr,omitempty"`
}

SuggestResponse — ответ поисковых подсказок.

type TransportError 

type TransportError struct {
	Kind error
	Err  error
}

TransportError — обмен не состоялся или оборвался. Kind говорит, какой именно: от него зависит, повторяем мы запрос или нет.

func (*TransportError) Error 

func (e *TransportError) Error() string

func (*TransportError) Is 

func (e *TransportError) Is(target error) bool

func (*TransportError) Unwrap 

func (e *TransportError) Unwrap() error

type VideoResponse 

type VideoResponse struct {
	Pages     int           `json:"pages"`
	Exhausted bool          `json:"exhausted"`
	Query     string        `json:"query"`
	URL       string        `json:"url,omitempty"`
	Results   []VideoResult `json:"results"`
}

VideoResponse — ответ поиска по видео.

type VideoResult 

type VideoResult struct {
	URL       string `json:"url"`
	Title     string `json:"title"`
	Domain    string `json:"domain"`
	Thumbnail string `json:"thumbnail,omitempty"`
	// Duration — длительность в секундах. nil означает «длина неизвестна»,
	// а не ноль: у прямых эфиров вместо подписи стоит LIVE.
	Duration      *int   `json:"duration,omitempty"`
	DurationText  string `json:"durationText,omitempty"`
	Published     int64  `json:"published,omitempty"`
	PublishedText string `json:"publishedText,omitempty"`
	// Views — просмотры подписью поисковика: 6,8K. Точного значения нет.
	Views       string `json:"views,omitempty"`
	Provider    string `json:"provider,omitempty"`
	Channel     string `json:"channel,omitempty"`
	Description string `json:"description,omitempty"`
	Breadcrumbs string `json:"breadcrumbs,omitempty"`
}

VideoResult — карточка видео.

type WordstatFrequencyResponse 

type WordstatFrequencyResponse struct {
	Text    string `json:"text"`
	Region  string `json:"region"`
	Device  string `json:"device"`
	Results struct {
		TotalValue int `json:"totalValue"`
	} `json:"results"`
	// Error — почему данных нет: Вордстат не принял фразу из-за синтаксиса
	// операторов. Ответ при этом удачный и оплаченный, а результаты пустые.
	// У обычного ответа поле пустое.
	Error string `json:"error,omitempty"`
}

WordstatFrequencyResponse — частота запроса одним числом.

type WordstatGraphPoint 

type WordstatGraphPoint struct {
	Date string `json:"date"`
	Text string `json:"text"`
	// Absolute — показы за период.
	Absolute int `json:"absolute"`
	// Relative — доля среди всех показов Яндекса.
	Relative float64 `json:"relative"`
}

WordstatGraphPoint — точка динамики показов.

type WordstatGraphResponse 

type WordstatGraphResponse struct {
	Text    string `json:"text"`
	Region  string `json:"region"`
	Device  string `json:"device"`
	Type    string `json:"type"`
	Results struct {
		Graph []WordstatGraphPoint `json:"graph"`
	} `json:"results"`
	// Error — почему данных нет: Вордстат не принял фразу из-за синтаксиса
	// операторов. Ответ при этом удачный и оплаченный, а результаты пустые.
	// У обычного ответа поле пустое.
	Error string `json:"error,omitempty"`
}

WordstatGraphResponse — динамика показов.

type WordstatMapResponse 

type WordstatMapResponse struct {
	Text    string `json:"text"`
	Device  string `json:"device"`
	Type    string `json:"type"`
	Results struct {
		Rows []WordstatMapRow `json:"rows"`
	} `json:"results"`
	// Error — почему данных нет: Вордстат не принял фразу из-за синтаксиса
	// операторов. Ответ при этом удачный и оплаченный, а результаты пустые.
	// У обычного ответа поле пустое.
	Error string `json:"error,omitempty"`
}

WordstatMapResponse — география показов.

type WordstatMapRow 

type WordstatMapRow struct {
	Type     string `json:"type"`
	Text     string `json:"text"`
	Absolute int    `json:"absolute"`
	// Popularity — affinity-индекс: 100 означает средний интерес.
	Popularity float64 `json:"popularity"`
	Relative   float64 `json:"relative"`
	// RegionID годится для параметра region других методов. nil, если
	// название неоднозначно.
	RegionID *int `json:"region_id"`
}

WordstatMapRow — строка географии показов.

type WordstatPhrase 

type WordstatPhrase struct {
	Text  string `json:"text"`
	Value int    `json:"value"`
}

WordstatPhrase — строка списка запросов Вордстата.

type WordstatResponse 

type WordstatResponse struct {
	Text    string `json:"text"`
	Region  string `json:"region"`
	Device  string `json:"device"`
	Results struct {
		// Popular — что ищут вместе с этой фразой.
		Popular []WordstatPhrase `json:"popular"`
		// Associations — соседняя семантика.
		Associations []WordstatPhrase `json:"associations"`
	} `json:"results"`
	// Error — почему данных нет: Вордстат не принял фразу из-за синтаксиса
	// операторов. Ответ при этом удачный и оплаченный, а результаты пустые.
	// У обычного ответа поле пустое.
	Error string `json:"error,omitempty"`
}

WordstatResponse — популярные и похожие запросы.

type YandexRegion 

type YandexRegion struct {
	ID      int     `json:"id"`
	Name    string  `json:"name"`
	Subname string  `json:"subname"`
	Lat     float64 `json:"lat"`
	Lon     float64 `json:"lon"`
}

YandexRegion — регион Яндекса из справочника.

type YandexRegionsResponse 

type YandexRegionsResponse struct {
	Name    string         `json:"name"`
	Lang    string         `json:"lang"`
	Regions []YandexRegion `json:"regions"`
}

YandexRegionsResponse — ответ справочника регионов Яндекса.

Source Files

View all Source files

Directories

Path Synopsis
examples
positions command
Позиции сайта в Яндексе по списку запросов.
 Позиции сайта в Яндексе по списку запросов.

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.