axioapi

package module
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 16 Imported by: 0

README

Go client for the AxioAPI REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API) and social scraper APIs. One API key, pay per request. Standard library only. Go 1.21+.

Get started in 3 steps

1. Get an API key

Create a free account, then open API keys, create a key and copy it. New accounts receive free credits after verification, enough to try every endpoint.

Set it as an environment variable (the SDK reads AXIOAPI_KEY):

export AXIOAPI_KEY=ak_your_key        # macOS / Linux
$env:AXIOAPI_KEY = "ak_your_key"      # Windows PowerShell
2. Install
go get github.com/axioapi/axioapi-go@main

Requires Go 1.21+. Standard library only.

3. Make your first call
package main

import (
	"context"
	"fmt"

	axioapi "github.com/axioapi/axioapi-go"
)

func main() {
	client, err := axioapi.New("") // empty reads AXIOAPI_KEY
	if err != nil {
		panic(err)
	}
	limits, err := client.Group("account").Call(context.Background(), "limits", nil)
	fmt.Println(string(limits), err)
}

Every endpoint works the same way: client.<group>.<operation>(params). See the examples below and the full reference.

More examples

package main

import (
	"context"
	"errors"
	"fmt"

	axioapi "github.com/axioapi/axioapi-go"
)

func main() {
	ctx := context.Background()
	client, err := axioapi.New("") // empty reads AXIOAPI_KEY
	if err != nil {
		panic(err)
	}

	// Keyword data API: volume, CPC and competition for up to 10 keywords per request
	var rows []struct {
		Keyword      string `json:"keyword"`
		SearchVolume int    `json:"search_volume"`
	}
	err = client.CallInto(ctx, "seo.keyword-metrics", axioapi.Params{"keywords": []string{"api gateway"}, "country": "us"}, &rows)

	// Backlink API: raw JSON, decode what you need
	data, err := client.Group("seo").Call(ctx, "backlinksSummary", axioapi.Params{"domain": "example.com"})
	fmt.Println(string(data), err)

	var apiErr *axioapi.APIError
	switch {
	case errors.Is(err, axioapi.ErrInsufficientCredits):
		fmt.Println("top up credits")
	case errors.As(err, &apiErr):
		fmt.Println(apiErr.Status, apiErr.Code, apiErr.RequestID, apiErr.RetryAfter)
	}
}
  • client.Group("seo").Call(ctx, "keywordMetrics", params) or client.Call(ctx, "seo.keyword-metrics", params) for every endpoint (camelCase, snake_case or kebab-case). client.Operations() lists all of them with method, path and credit cost.
  • Call returns the data field as json.RawMessage; CallInto decodes it; Request returns the status, headers and whole envelope; CallBinary returns file bytes.
  • Errors are *APIError and match errors.Is with ErrAuthentication, ErrInsufficientCredits, ErrNotFound, ErrValidation and ErrRateLimit. Network failures are *ConnectionError.
  • Options: WithBaseURL, WithHTTPClient, WithMaxRetries(2), WithUserAgent. 429 is retried for all methods; 502/503/504 and network errors only for GET and DELETE. Pass a context to cancel.

Docs: https://axioapi.com/docs · Guides: https://axioapi.com/guides · License: MIT

What you can build with the Go SDK

Use case API page Typical call
Temp mail API: disposable inboxes for signup and password-reset tests temporary-email create inbox, list messages, read message
Receive SMS API and OTP API: public numbers and "wait for the code" sms, verify list numbers, wait for OTP
Email validation API: syntax, MX and disposable-address checks, plus transactional and outreach email sending email validate, batch validate, send
Proxy API: sticky and rotating proxy sessions by country proxy create session, rotate, close
SEO API: keyword data API (volume, CPC), backlink API, domain overview, on-page audit seo keyword metrics, backlinks summary
Search API: web, image, news, video, maps and shopping results, AI Overview and autocomplete search web search, news search
Scholar API: Google Scholar paper search, author profiles and citation formats scholar search papers, author profile
Text AI: neural translation, text generation and grammar check text, grammar translate, generate, check grammar
Audio and video AI: speech-to-text, text-to-speech, AI image generation, video transcripts and tags audio, tts, ai-image, video transcribe, text to speech, generate image
YouTube AI summarizer and webpage content extraction youtube, webpage summarize video, extract page
Coupon API and product price history: store promo codes and historical prices coupons, products, ecommerce search coupons, price history
DNS, BIN, technology and local lead APIs: DNS records, card BIN lookup, website tech stack, Google Maps business leads dns, bin, tech, local resolve DNS, BIN lookup, tech profile
TikTok, Facebook, Instagram, YouTube, X (Twitter), LinkedIn and Reddit scraper APIs social profiles, posts, comments, transcripts

Guides with working code

Free tools that need no account: backlink checker, email validator, DNS lookup, BIN checker.

FAQ

Is there a Go client for the AxioAPI backlink API and keyword data API? Yes, this package. seo.backlinks_summary returns the backlink summary of a domain with the figures of every data source, and seo.keyword_metrics returns search volume, CPC and competition for up to 10 keywords per request.

How do I test signup emails and OTP codes from Go? Create a disposable inbox with the temp mail API, submit its address in your form and read the message. For SMS codes, call the verify endpoint, which waits for the OTP on a public number and returns it.

How much does it cost? You pay per request with credits, and each endpoint lists its price on its API page and in the OpenAPI spec (x-credit-cost). New accounts receive free credits after verification. See pricing.

Where is the full reference? axioapi.com/docs, the OpenAPI 3.1 spec and llms.txt for AI agents.

Vietnamese: AxioAPI tiếng Việt, API SEO và API backlink.

Documentation

Overview

Package axioapi is the official Go SDK for the AxioAPI REST API (https://axioapi.com): temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API), search API and social scraper APIs.

c, _ := axioapi.New("ak_...")
data, err := c.Group("seo").Call(ctx, "keywordMetrics", axioapi.Params{"keywords": []string{"api gateway"}, "country": "us"})

Index

Constants

View Source
const Version = "1.0.0"

Version is the SDK version.

Variables

View Source
var (
	ErrAuthentication      = errors.New("axioapi: authentication failed")
	ErrInsufficientCredits = errors.New("axioapi: insufficient credits")
	ErrNotFound            = errors.New("axioapi: not found")
	ErrValidation          = errors.New("axioapi: validation failed")
	ErrRateLimit           = errors.New("axioapi: rate limited")
)

Sentinel errors for errors.Is.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	Status    int
	Code      string
	Message   string
	RequestID string
	// Fields holds per-field messages for 422 responses.
	Fields map[string][]string
	// RetryAfter is in seconds for 429 responses, 0 when the server sent none.
	RetryAfter float64
	Body       json.RawMessage
}

APIError is returned for every non-2xx response. Use errors.Is with the Err* sentinels or errors.As to read fields.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Is

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

Is lets errors.Is(err, axioapi.ErrRateLimit) and friends match by HTTP status.

type Client

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

Client talks to the AxioAPI. It is safe for concurrent use.

func New

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

New creates a client. An empty apiKey falls back to the AXIOAPI_KEY environment variable.

func (*Client) Call

func (c *Client) Call(ctx context.Context, operation string, params Params) (json.RawMessage, error)

Call runs an operation by capability key (for example "seo.keyword-metrics") and returns its data.

func (*Client) CallBinary

func (c *Client) CallBinary(ctx context.Context, operation string, params Params) ([]byte, error)

CallBinary runs an operation that returns a file (image or audio).

func (*Client) CallInto

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

CallInto runs an operation and decodes its data into out.

func (*Client) Group

func (c *Client) Group(name string) *Group

Group scopes calls to one API group, for example c.Group("seo").Call(ctx, "keywordMetrics", params).

func (*Client) Operations

func (c *Client) Operations() map[string]Operation

Operations returns the registry of every operation.

func (*Client) Request

func (c *Client) Request(ctx context.Context, method, path string, query url.Values, body any) (*Response, error)

Request sends a request with retries and returns the parsed response. body may be nil.

func (*Client) Resolve

func (c *Client) Resolve(group, name string) (string, bool)

Resolve returns the capability key for a group and operation name (any of camelCase, snake_case, kebab-case).

type ConnectionError

type ConnectionError struct{ Message string }

ConnectionError means the request never produced an HTTP response (DNS, TLS, timeout).

func (*ConnectionError) Error

func (e *ConnectionError) Error() string

type Group

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

Group is a set of operations that share a prefix.

func (*Group) Call

func (g *Group) Call(ctx context.Context, operation string, params Params) (json.RawMessage, error)

Call runs an operation and returns its data.

func (*Group) CallBinary

func (g *Group) CallBinary(ctx context.Context, operation string, params Params) ([]byte, error)

CallBinary runs an operation that returns a file.

type Operation

type Operation struct {
	Key        string   `json:"-"`
	Method     string   `json:"method"`
	Path       string   `json:"path"`
	Summary    string   `json:"summary"`
	Cost       *float64 `json:"cost"`
	PathParams []string `json:"path_params"`
	Query      []string `json:"query"`
	Body       []string `json:"body"`
	Binary     bool     `json:"binary"`
}

Operation describes one API operation from the registry.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides https://axioapi.com.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient replaces the default http.Client (set your own Timeout or Transport).

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets retries for 429 and, on GET/DELETE, 502/503/504 and network errors. Default 2.

func WithSleep

func WithSleep(f func(context.Context, time.Duration) error) Option

WithSleep replaces the backoff sleep (used by tests).

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent overrides the User-Agent header.

type Params

type Params map[string]any

Params are the parameters of an operation: path, query and body values in one map.

type Response

type Response struct {
	Status int
	Header http.Header
	// Data is the "data" field of the envelope (nil for files).
	Data json.RawMessage
	// Envelope is the whole JSON body (nil for files).
	Envelope json.RawMessage
	// Bytes is set instead of Data when the response is not JSON (images, audio).
	Bytes []byte
}

Response is a raw API response.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL