asin

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2026 License: MIT Imports: 18 Imported by: 0

README

Asin Go SDK

The official Go SDK for the Asin Amazon price tracking API.

Track Amazon prices and products with a scheduled watchlist, price history, offers and alerts.

The SDK exposes 11 typed methods, one per documented endpoint, plus a generic Request(). It has no dependencies outside the standard library.

Requirements

  • Go 1.22 or newer

Installation

go get github.com/asindotdev/asin-go

Get your API key

Sign up for Asin or sign in, then copy your API key from the dashboard. NewClient("", nil) reads the ASIN_API_KEY environment variable.

Quick start

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/asindotdev/asin-go"
)

func main() {
	client, err := asin.NewClient("", nil) // reads ASIN_API_KEY
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()
	response, err := client.SearchAmazon(ctx, &asin.SearchAmazonParams{Query: "wireless earbuds"})
	if err != nil {
		log.Fatal(err)
	}
	data, err := response.Map()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(data)
}

Parameter structs mirror the API reference. Required fields are plain values; optional fields are pointers — use asin.String, asin.Float, asin.Int and asin.Bool.

Decode into your own types with response.Decode(&value).

HTTP methods

Each method uses the HTTP verb of its endpoint. GET and DELETE send parameters in the query string; POST and PATCH send them as a JSON body, except wait on /products/{id}/check, which stays in the query string. Null values are never sent, so target_price cannot be removed through the SDK yet.

Any endpoint

response, err := client.Request(ctx, "GET", "/account", nil)

Errors

response, err := client.SearchAmazon(ctx, &asin.SearchAmazonParams{Query: "wireless earbuds"})
if apiError, ok := asin.IsAPIError(err); ok {
	log.Printf("HTTP %d: %s", apiError.StatusCode, apiError.Message)
}
Error When
*ConfigurationError Missing API key, invalid options or unsupported method.
*SerializationError A required parameter is missing or a value can't be sent.
*TransportError Network failure, timeout or cancelled context (errors.Is(err, context.DeadlineExceeded)).
*APIError Non-2xx status (StatusCode, Message, Response).
*ResponseDecodingError A success response could not be decoded.

Retries

Requests are retried up to 3 times after a network error, a 408, 429, 500, 502, 503 or 504. Other statuses, such as 400, 401, 402 or 404, and client-side timeouts are not retried. The delay starts at 1 second and grows 1.5× per retry (capped at 30 seconds); a Retry-After header wins.

client, err := asin.NewClient("", &asin.ClientOptions{
	MaxRetries: 5,                      // negative disables retries
	RetryDelay: 500 * time.Millisecond,
})

// or for one request
response, err := client.SearchAmazon(ctx, &asin.SearchAmazonParams{Query: "wireless earbuds"}, asin.WithMaxRetries(0))

Batch requests

asin.Batch runs a function per item with at most 10 calls in flight and returns one BatchResult per item, in input order. A failing item never stops the others.

inputs := []string{"wireless earbuds", "mechanical keyboard", "usb-c hub"}
results := asin.Batch(ctx, inputs, 5, func(ctx context.Context, value string) (*asin.Response, error) {
	return client.SearchAmazon(ctx, &asin.SearchAmazonParams{Query: value})
})
for _, result := range results {
	if result.Err != nil {
		log.Printf("%s: %v", inputs[result.Index], result.Err)
		continue
	}
	fmt.Println(string(result.Value.Body))
}
Constant Default Description
DefaultConcurrency 10 Tasks run at the same time by batch
DefaultTimeout 120 * time.Second Request timeout
MaxRetries 3 Retry attempts after a network error, a 408/429/5xx
RetryBackoffFactor 1.5 Exponential backoff multiplier
DefaultRetryDelay time.Second Delay before the first retry

Timeouts and custom HTTP clients

client, err := asin.NewClient("", &asin.ClientOptions{
	Timeout:    60 * time.Second, // default 120 s; negative disables
	HTTPClient: &http.Client{Transport: myTransport},
})

Every method also honours the deadline and cancellation of the context.Context you pass.

Endpoints

11 methods, generated from the OpenAPI document.

Method HTTP Description
CheckProduct POST /products/{id}/check Asks for a check right away (1 credit), at most once per 5 minutes; earlier calls return the product unchanged. A paused product has to be…
DeleteProduct DELETE /products/{id} Removes the product and its price history.
FetchOffers POST /offers Reads the offers on Amazon for 1 credit, refunded if it doesn't answer. A read made in the last 3 hours, by anyone, is returned instead, fo…
GetAccount GET /account Your plan, the credits left (monthly allowance and packs), how many products you track and the credits they use per month.
GetAsinHistory GET /history Every price Asin read for an ASIN on a marketplace over the period, whoever tracks it, oldest first, with the lowest, highest and average o…
GetOffers GET /offers Who sells the product and at what price, as last read, cheapest first, with Amazon's own price and the cheapest new and used offers (used i…
GetProduct GET /products/{id} The product's latest state and every price read of the period, oldest first. The history covers every read of this ASIN on this marketplace…
ListProducts GET /products Your watchlist, newest first, with each product's latest state and its recent prices (trend). Filter with asin (and marketplace) to know if…
SearchAmazon GET /search Amazon search results (up to 60, sponsored included), to find the ASIN of a product. Free, limited to 30 searches per hour.
TrackProduct POST /products Adds an ASIN, an Amazon link or a short link (amzn.to, a.co…) to your watchlist. The first check runs in the background within seconds (che…
UpdateProduct PATCH /products/{id} Target price, drop alerts, check interval, or pause. Send only what changes.

License

MIT — see LICENSE.

Documentation

Overview

Package asin is the official Go SDK for the Asin API (https://www.asin.dev).

Track Amazon prices and products with a scheduled watchlist, price history, offers and alerts.

Create one client and reuse it: 

client, err := asin.NewClient("", nil) // reads ASIN_API_KEY
response, err := client.SearchAmazon(ctx, ...)

Every documented endpoint has a typed method; Client.Request reaches any other path.

Index

Constants

View Source 
const (
	// DefaultBaseURL is the production API origin.
	DefaultBaseURL = "https://www.asin.dev/api/v1"
	// DefaultTimeout bounds every request unless ClientOptions.Timeout says otherwise.
	DefaultTimeout = 120 * time.Second
	// APIKeyEnvironmentVariable is read when NewClient receives an empty API key.
	APIKeyEnvironmentVariable = "ASIN_API_KEY"
	// DefaultConcurrency is the number of tasks Batch runs at the same time.
	DefaultConcurrency = 10
	// MaxRetries is the default number of retries after a network error or a 408, 429, 500, 502, 503 or 504.
	MaxRetries = 3
	// RetryBackoffFactor multiplies the delay before each new retry (a Retry-After header wins).
	RetryBackoffFactor = 1.5
	// DefaultRetryDelay is the delay before the first retry.
	DefaultRetryDelay = time.Second
	// MaxRetryDelay caps the delay between two attempts.
	MaxRetryDelay = 30 * time.Second
)
View Source 
const Version = "0.1.0"

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

Variables

This section is empty.

Functions

func Bool 

func Bool(v bool) *bool

Bool returns a pointer to v, for optional boolean parameters.

func Float 

func Float(v float64) *float64

Float returns a pointer to v, for optional number parameters.

func Int 

func Int(v int64) *int64

Int returns a pointer to v, for optional integer parameters.

func String 

func String(v string) *string

String returns a pointer to v, for optional parameters.

Types

type APIError 

type APIError struct {
	StatusCode int
	// Message is the "error" (or "message") field of the JSON body, when present.
	Message  string
	Response *Response
}

APIError is returned for non-2xx responses.

func IsAPIError 

func IsAPIError(err error) (*APIError, bool)

IsAPIError reports whether err is an *APIError and returns it.

func (*APIError) Error 

func (e *APIError) Error() string

type BatchResult 

type BatchResult[T any] struct {
	Index int
	Value T
	Err   error
}

BatchResult is the outcome of one Batch item.

func Batch 

func Batch[I, T any](ctx context.Context, items []I, concurrency int, task func(ctx context.Context, item I) (T, error)) []BatchResult[T]

Batch runs task for every item with at most concurrency calls in flight (DefaultConcurrency when concurrency <= 0) and returns one result per item, in input order. A failing item never stops the others; items not started when ctx is done get ctx.Err().

type CheckProductParams 

type CheckProductParams struct {
	// product_id returned when the product was added
	ID string `json:"id" api:"id,required"`
	// Answer once the check is done (up to 45 seconds) Default: false.
	Wait *bool `json:"wait" api:"wait"`
}

CheckProductParams holds the parameters of CheckProduct (POST /products/{id}/check). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type Client 

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

Client is a reusable, concurrency-safe Asin API client.

func NewClient 

func NewClient(apiKey string, options *ClientOptions) (*Client, error)

NewClient creates a client. An empty apiKey falls back to the ASIN_API_KEY environment variable.

func (*Client) CheckProduct 

func (c *Client) CheckProduct(ctx context.Context, params *CheckProductParams, options ...RequestOption) (*Response, error)

CheckProduct — Check the price now. Asks for a check right away (1 credit), at most once per 5 minutes; earlier calls return the product unchanged. A paused product has to be resumed first. The check runs in the background; with wait=true the answer waits for it. Read last_e…

POST /products/{id}/check

func (*Client) DeleteProduct 

func (c *Client) DeleteProduct(ctx context.Context, params *DeleteProductParams, options ...RequestOption) (*Response, error)

DeleteProduct — Stop tracking a product. Removes the product and its price history.

DELETE /products/{id}

func (*Client) FetchOffers 

func (c *Client) FetchOffers(ctx context.Context, params *FetchOffersParams, options ...RequestOption) (*Response, error)

FetchOffers — Read every offer from Amazon. Reads the offers on Amazon for 1 credit, refunded if it doesn't answer. A read made in the last 3 hours, by anyone, is returned instead, for free (charged: false). The answer is the same as GET /offers.

POST /offers

func (*Client) GetAccount 

func (c *Client) GetAccount(ctx context.Context, options ...RequestOption) (*Response, error)

GetAccount — Plan and remaining credits. Your plan, the credits left (monthly allowance and packs), how many products you track and the credits they use per month.

GET /account

func (*Client) GetAsinHistory 

func (c *Client) GetAsinHistory(ctx context.Context, params *GetAsinHistoryParams, options ...RequestOption) (*Response, error)

GetAsinHistory — Price history of any ASIN. Every price Asin read for an ASIN on a marketplace over the period, whoever tracks it, oldest first, with the lowest, highest and average of those prices. A history of more than 5000 points is thinned evenly, keeping its first and last poi…

GET /history

func (*Client) GetOffers 

func (c *Client) GetOffers(ctx context.Context, params *GetOffersParams, options ...RequestOption) (*Response, error)

GetOffers — Offers already known. Who sells the product and at what price, as last read, cheapest first, with Amazon's own price and the cheapest new and used offers (used is only known for Amazon's own outlet). Free: this never reads Amazon or spends a credit. When nobody…

GET /offers

func (*Client) GetProduct 

func (c *Client) GetProduct(ctx context.Context, params *GetProductParams, options ...RequestOption) (*Response, error)

GetProduct — Get a product and its price history. The product's latest state and every price read of the period, oldest first. The history covers every read of this ASIN on this marketplace, including those made before you added it, so a product added today can come with months of prices;…

GET /products/{id}

func (*Client) ListProducts 

func (c *Client) ListProducts(ctx context.Context, params *ListProductsParams, options ...RequestOption) (*Response, error)

ListProducts — List tracked products. Your watchlist, newest first, with each product's latest state and its recent prices (trend). Filter with asin (and marketplace) to know if a product is tracked, or with filter to get the same lists as the app's tabs.

GET /products

func (*Client) Request 

func (c *Client) Request(ctx context.Context, method, path string, params map[string]any, options ...RequestOption) (*Response, error)

Request sends any request, including endpoints released after this SDK version. GET parameters travel in the query string; POST parameters travel in a JSON body.

func (*Client) SearchAmazon 

func (c *Client) SearchAmazon(ctx context.Context, params *SearchAmazonParams, options ...RequestOption) (*Response, error)

SearchAmazon — Search Amazon. Amazon search results (up to 60, sponsored included), to find the ASIN of a product. Free, limited to 30 searches per hour.

GET /search

func (*Client) TrackProduct 

func (c *Client) TrackProduct(ctx context.Context, params *TrackProductParams, options ...RequestOption) (*Response, error)

TrackProduct — Track a product. Adds an ASIN, an Amazon link or a short link (amzn.to, a.co…) to your watchlist. The first check runs in the background within seconds (checking is true until then): poll GET /products/{id}, or send wait: true to get the answer once it's d…

POST /products

func (*Client) UpdateProduct 

func (c *Client) UpdateProduct(ctx context.Context, params *UpdateProductParams, options ...RequestOption) (*Response, error)

UpdateProduct — Change alerts and checks. Target price, drop alerts, check interval, or pause. Send only what changes.

PATCH /products/{id}

type ClientOptions 

type ClientOptions struct {
	// BaseURL overrides DefaultBaseURL.
	BaseURL string
	// Timeout bounds each request. Zero uses DefaultTimeout; a negative value disables it.
	Timeout time.Duration
	// HTTPClient is copied and used for requests. Redirects are never followed.
	HTTPClient *http.Client
	// Headers are sent with every request.
	Headers map[string]string
	// MaxRetries overrides the number of retries. Zero uses MaxRetries; a negative value disables retries.
	MaxRetries int
	// RetryDelay is the delay before the first retry. Zero uses DefaultRetryDelay.
	RetryDelay time.Duration
}

ClientOptions configures a Client. The zero value is valid.

type ConfigurationError 

type ConfigurationError struct {
	Message string
	Err     error
}

ConfigurationError reports a missing or unusable client configuration.

func (*ConfigurationError) Error 

func (e *ConfigurationError) Error() string

func (*ConfigurationError) Unwrap 

func (e *ConfigurationError) Unwrap() error

type DeleteProductParams 

type DeleteProductParams struct {
	// product_id returned when the product was added
	ID string `json:"id" api:"id,required"`
}

DeleteProductParams holds the parameters of DeleteProduct (DELETE /products/{id}). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type FetchOffersParams 

type FetchOffersParams struct {
	// 10-character ASIN
	Asin string `json:"asin" api:"asin,required"`
	// Amazon store, e.g. com for amazon.com Allowed values: com, co.uk, de, fr, it, es, ca, co.jp, com.br, com.mx, in. Default: "com".
	Marketplace *string `json:"marketplace" api:"marketplace"`
	// Read Amazon again unless the last read is under 5 minutes old (1 credit) Default: false.
	Refresh *bool `json:"refresh" api:"refresh"`
}

FetchOffersParams holds the parameters of FetchOffers (POST /offers). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type GetAsinHistoryParams 

type GetAsinHistoryParams struct {
	// 10-character ASIN
	Asin string `json:"asin" api:"asin,required"`
	// Amazon store, e.g. com for amazon.com Allowed values: com, co.uk, de, fr, it, es, ca, co.jp, com.br, com.mx, in. Default: "com".
	Marketplace *string `json:"marketplace" api:"marketplace"`
	// History period in days Default: 90.
	Days *int64 `json:"days" api:"days"`
}

GetAsinHistoryParams holds the parameters of GetAsinHistory (GET /history). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type GetOffersParams 

type GetOffersParams struct {
	// 10-character ASIN
	Asin string `json:"asin" api:"asin,required"`
	// Amazon store, e.g. com for amazon.com Allowed values: com, co.uk, de, fr, it, es, ca, co.jp, com.br, com.mx, in. Default: "com".
	Marketplace *string `json:"marketplace" api:"marketplace"`
}

GetOffersParams holds the parameters of GetOffers (GET /offers). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type GetProductParams 

type GetProductParams struct {
	// product_id returned when the product was added
	ID string `json:"id" api:"id,required"`
	// History period in days Default: 90.
	Days *int64 `json:"days" api:"days"`
}

GetProductParams holds the parameters of GetProduct (GET /products/{id}). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type ListProductsParams 

type ListProductsParams struct {
	// Only this ASIN
	Asin *string `json:"asin" api:"asin"`
	// Only this Amazon store Allowed values: com, co.uk, de, fr, it, es, ca, co.jp, com.br, com.mx, in.
	Marketplace *string `json:"marketplace" api:"marketplace"`
	// Only the products of one of the app's watchlist filters. all: Every tracked product (default). drops: Cheaper now than when the product was added. target: At or below its target price. out_of_stock: No offer at the last check. attention: The last check didn't go through (last_error is set): no cred…
	Filter *string `json:"filter" api:"filter"`
	// Page number Default: 1.
	Page *int64 `json:"page" api:"page"`
	// Products per page Default: 20.
	Limit *int64 `json:"limit" api:"limit"`
}

ListProductsParams holds the parameters of ListProducts (GET /products). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type RequestOption 

type RequestOption func(*requestOptions)

RequestOption customizes one request.

func WithHeader 

func WithHeader(name, value string) RequestOption

WithHeader adds a header to one request.

func WithMaxRetries 

func WithMaxRetries(n int) RequestOption

WithMaxRetries overrides the number of retries for one request (0 disables them).

func WithMethod 

func WithMethod(method string) RequestOption

WithMethod selects the HTTP method. Operations default to their own method.

type Response 

type Response struct {
	StatusCode  int
	Header      http.Header
	ContentType string
	// Body holds the raw bytes: JSON text, or a file such as an image or PDF.
	Body []byte
	// IsJSON reports whether the body is JSON (Content-Type application/json or +json).
	IsJSON bool
}

Response is a buffered, successful API response.

func (*Response) Decode 

func (r *Response) Decode(v any) error

Decode unmarshals a JSON body into v.

func (*Response) Map 

func (r *Response) Map() (map[string]any, error)

Map decodes a JSON object body.

type ResponseDecodingError 

type ResponseDecodingError struct {
	Message  string
	Response *Response
	Err      error
}

ResponseDecodingError reports a success response that could not be decoded.

func (*ResponseDecodingError) Error 

func (e *ResponseDecodingError) Error() string

func (*ResponseDecodingError) Unwrap 

func (e *ResponseDecodingError) Unwrap() error

type SearchAmazonParams 

type SearchAmazonParams struct {
	// Keywords
	Query string `json:"query" api:"query,required"`
	// Amazon store, e.g. com for amazon.com Allowed values: com, co.uk, de, fr, it, es, ca, co.jp, com.br, com.mx, in. Default: "com".
	Marketplace *string `json:"marketplace" api:"marketplace"`
}

SearchAmazonParams holds the parameters of SearchAmazon (GET /search). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type SerializationError 

type SerializationError struct {
	Param   string
	Message string
	Err     error
}

SerializationError reports a parameter that is missing or cannot be sent.

func (*SerializationError) Error 

func (e *SerializationError) Error() string

func (*SerializationError) Unwrap 

func (e *SerializationError) Unwrap() error

type TrackProductParams 

type TrackProductParams struct {
	// ASIN (B09DFCB66S) or Amazon product link
	Product string `json:"product" api:"product,required"`
	// Amazon store, e.g. com for amazon.com. A product link sets it on its own. Allowed values: com, co.uk, de, fr, it, es, ca, co.jp, com.br, com.mx, in. Default: "com".
	Marketplace *string `json:"marketplace" api:"marketplace"`
	// Email the owner when the price goes at or below this amount. null removes it.
	TargetPrice *float64 `json:"target_price" api:"target_price"`
	// Minutes between two checks (1440 = daily). Checks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business. Default: 1440.
	IntervalMinutes *int64 `json:"interval_minutes" api:"interval_minutes"`
	// Answer once the first check is done (up to 45 seconds) Default: false.
	Wait *bool `json:"wait" api:"wait"`
}

TrackProductParams holds the parameters of TrackProduct (POST /products). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

type TransportError 

type TransportError struct {
	Message string
	Err     error
}

TransportError reports a failure before a complete HTTP response was received, including client-side timeouts and context cancellation (see Unwrap).

func (*TransportError) Error 

func (e *TransportError) Error() string

func (*TransportError) Unwrap 

func (e *TransportError) Unwrap() error

type UpdateProductParams 

type UpdateProductParams struct {
	// product_id returned when the product was added
	ID string `json:"id" api:"id,required"`
	// Email the owner when the price goes at or below this amount. null removes it.
	TargetPrice *float64 `json:"target_price" api:"target_price"`
	// Minutes between two checks (1440 = daily). Checks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business. Default: 1440.
	IntervalMinutes *int64 `json:"interval_minutes" api:"interval_minutes"`
	// Email when the price drops or the product is back in stock
	AlertOnDrop *bool `json:"alert_on_drop" api:"alert_on_drop"`
	// Stop checking (and charging) for now; false resumes
	Paused *bool `json:"paused" api:"paused"`
}

UpdateProductParams holds the parameters of UpdateProduct (PATCH /products/{id}). Required fields are plain values; optional fields are pointers (use asin.String, asin.Float, asin.Bool) or nil slices and maps.

Source Files

View all Source files

Directories

Path Synopsis
examples
json command
request 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.