Go
Install the HuntAPI Go SDK and make your first API call.
The official Go SDK for HuntAPI, with one typed method per endpoint and a generic request() for anything else.
Requirements
- Go 1.22+
Install
go get github.com/huntapi/huntapi-goGet your API key
Copy your API key from the HuntAPI dashboard and set it in the HUNTAPI_API_KEY environment variable, which the SDK reads by default. Keep it out of source control.
Quick start
package main
import (
"context"
"fmt"
"log"
"github.com/huntapi/huntapi-go"
)
func main() {
client, err := huntapi.NewClient("", nil) // reads HUNTAPI_API_KEY
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
response, err := client.MediaMetadata(ctx, &huntapi.MediaMetadataParams{Query: "https://www.youtube.com/watch?v=Z5YP8kznWZs"})
if err != nil {
log.Fatal(err)
}
data, err := response.Map()
if err != nil {
log.Fatal(err)
}
fmt.Println(data)
}Async jobs
Download endpoints are asynchronous: they return a job_id, and jobs can run for up to 12 hours. The SDK can wait for the job to finish.
submitted, err := client.VideoDownload(ctx, &huntapi.VideoDownloadParams{Query: "https://www.youtube.com/watch?v=Z5YP8kznWZs", VideoQuality: huntapi.String("720p")})
if err != nil {
log.Fatal(err)
}
var accepted struct{ JobID string `json:"job_id"` }
if err := submitted.Decode(&accepted); err != nil {
log.Fatal(err)
}
job, err := client.WaitForJob(ctx, accepted.JobID, &huntapi.WaitForJobOptions{
OnProgress: func(job map[string]any) { fmt.Println(job["status"], job["progress"]) },
})Errors
A non-2xx response raises an API error with its status and message. See Status codes for the full list.
response, err := client.MediaMetadata(ctx, &huntapi.MediaMetadataParams{Query: "https://www.youtube.com/watch?v=Z5YP8kznWZs"})
if apiError, ok := huntapi.IsAPIError(err); ok {
log.Printf("HTTP %d: %s", apiError.StatusCode, apiError.Message)
}Retries
Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a plan rate limit. Per-key quota errors and client-side timeouts are not retried. The delay starts at 1 second and grows 1.5× per retry, and a Retry-After header wins.
client, err := huntapi.NewClient("", &huntapi.ClientOptions{
MaxRetries: 5, // negative disables retries
RetryDelay: 500 * time.Millisecond,
})
// or for one request
response, err := client.MediaMetadata(ctx, &huntapi.MediaMetadataParams{Query: "https://www.youtube.com/watch?v=Z5YP8kznWZs"}, huntapi.WithMaxRetries(0))Batch requests
Run many calls at once, 10 at a time by default. One failure does not stop the others.
inputs := []string{"https://www.youtube.com/watch?v=Z5YP8kznWZs", "https://www.youtube.com/watch?v=jNQXAC9IVRw"}
results := huntapi.Batch(ctx, inputs, 5, func(ctx context.Context, value string) (*huntapi.Response, error) {
return client.MediaMetadata(ctx, &huntapi.MediaMetadataParams{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))
}Any endpoint
request() reaches any path, including endpoints released after your SDK version.
response, err := client.Request(ctx, "GET", "/v1/usage", nil)Common mistakes
- Putting the API key in front-end code. Anyone could read it. Call the API from your server.
- Treating every
401as a bad key. A401can also be a rate limit: read the message. The SDK retries plan rate limits for you. - Retrying a
402. It means there are no credits or quota left, so a retry cannot succeed. See Credits. - Waiting on long requests. Past 60 seconds, use async mode as shown above rather than raising your timeout. See Timeout.
Links
- Package:
huntapi-go - Source code: github.com/huntapi/huntapi-go
- API reference