README
¶
maclookup-go
A Go client library for the maclookup.app API v2.
Given any MAC address (or just its OUI/prefix), the library resolves the IEEE-registered vendor information — company name, address, country, block type and range — in a single HTTP call. It handles rate-limit headers, API key authentication, timeouts, and all documented error responses.
Features
- Full MAC lookup — resolve MAC prefix → company name, address, country, block start/end/size/type, last-updated date,
isRand,isPrivateflags. - Lightweight company-name lookup — retrieve only the vendor name (faster, cheaper on quota).
- Rate-limit awareness — every response exposes
RateLimit.Limit,Remaining, andResetso callers can back off gracefully. - Flexible MAC input — accepts any common notation:
AA:BB:CC:DD:EE:FF,AA-BB-CC,AABBCC,AA.BB.CC, etc. - Typed errors — distinguish network errors, bad requests, invalid API keys, and rate-limit violations with
errors.As. - Configurable — custom timeout, API key, or base URL (useful for testing against a local proxy).
Installation
Requires Go 1.16 or later.
go get github.com/logocomune/maclookup-go
Quick Start
Look up full vendor information
package main
import (
"fmt"
"log"
"github.com/logocomune/maclookup-go"
)
func main() {
client := maclookup.New()
r, err := client.Lookup("00:00:00:00:00:00")
if err != nil {
log.Fatal(err)
}
fmt.Println("Found: ", r.Found)
fmt.Println("Company: ", r.Company)
fmt.Println("Address: ", r.Address)
fmt.Println("Country: ", r.Country)
fmt.Println("Block type: ", r.BlockType)
fmt.Println("Updated: ", r.Updated)
fmt.Println("Private: ", r.IsPrivate)
fmt.Println("Random: ", r.IsRand)
fmt.Println("Response time:", r.RespTime)
}
Look up company name only
client := maclookup.New()
r, err := client.CompanyName("00:00:00")
if err != nil {
log.Fatal(err)
}
fmt.Println("Found: ", r.Found)
fmt.Println("Private: ", r.IsPrivate)
fmt.Println("Company: ", r.Company)
Configuration
API key
Free-tier accounts are subject to strict rate limits. Register at https://maclookup.app/api-v2/plans and pass your key to the client:
client := maclookup.New()
client.WithAPIKey("your_api_key_here")
Custom timeout
The default per-request timeout is 5 seconds.
client := maclookup.New()
client.WithTimeout(10 * time.Second)
Custom base URL
Useful for routing through a proxy or pointing at a local mock server during tests:
client := maclookup.New()
client.WithPrefixURI("http://localhost:8080")
Error Handling
All errors returned by Lookup and CompanyName are typed and can be inspected with errors.As:
| Error type | When returned |
|---|---|
*maclookup.BadAPIRequest |
HTTP 400 — invalid MAC or query parameter |
*maclookup.BadAPIKey |
HTTP 401 — missing or invalid API key |
*maclookup.RateLimitsExceeded |
HTTP 429 — quota exhausted; check e.Limit and e.Reset |
*maclookup.BadAPIResponse |
HTTP 200 but unreadable response body |
*maclookup.HTTPClientError |
Network/transport error or unexpected HTTP status |
import (
"errors"
"log"
"github.com/logocomune/maclookup-go"
)
client := maclookup.New()
r, err := client.Lookup("00:00:00")
if err != nil {
var rateLimitErr *maclookup.RateLimitsExceeded
var badKeyErr *maclookup.BadAPIKey
switch {
case errors.As(err, &rateLimitErr):
log.Printf("rate limited — quota: %d, resets at: %s",
rateLimitErr.Limit, rateLimitErr.Reset)
case errors.As(err, &badKeyErr):
log.Println("check your API key:", badKeyErr)
default:
log.Println("lookup failed:", err)
}
return
}
// r.Found is false when the prefix is not in the database
if !r.Found {
log.Println("MAC prefix not found")
return
}
log.Println(r.Company)
Rate Limits
Every successful response (even when Found is false) populates RateLimit:
r, _ := client.Lookup("00:00:00")
fmt.Println("Quota remaining:", r.RateLimit.Remaining)
fmt.Println("Resets at: ", r.RateLimit.Reset)
To stay within limits, apply a client-side rate limiter (see the rate-limit example).
Examples
| Example | Description |
|---|---|
| example/lookup | Full MAC lookup |
| example/company-name | Vendor name only |
| example/rate-limit | Client-side rate limiting with golang.org/x/time/rate |
API Reference
Full Go documentation is available via go doc or pkg.go.dev.
License
MIT — see LICENSE.
Documentation
¶
Overview ¶
Package maclookup implements the MACLookup API v2.
Api documentation: https://maclookup.app/api-v2/documentation
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BadAPIKey ¶
type BadAPIKey struct {
Err error
}
BadAPIKey is returned when the API responds with HTTP 401, indicating that the supplied API key is missing or invalid.
type BadAPIRequest ¶
type BadAPIRequest struct {
Err error
}
BadAPIRequest is returned when the API responds with HTTP 400, indicating that the supplied MAC address or query parameters are invalid.
func (*BadAPIRequest) Error ¶
func (c *BadAPIRequest) Error() string
Error implements the error interface.
func (*BadAPIRequest) Unwrap ¶
func (c *BadAPIRequest) Unwrap() error
Unwrap returns the underlying error.
type BadAPIResponse ¶
type BadAPIResponse struct {
Err error
}
BadAPIResponse is returned when the API returns HTTP 200 but the response body cannot be decoded or does not indicate success.
func (*BadAPIResponse) Error ¶
func (c *BadAPIResponse) Error() string
Error implements the error interface.
func (*BadAPIResponse) Unwrap ¶
func (c *BadAPIResponse) Unwrap() error
Unwrap returns the underlying error.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the maclookup.app API client. Create one with New() and optionally configure it with WithAPIKey, WithTimeout, or WithPrefixURI.
func New ¶
func New() *Client
New creates a new Client for the maclookup.app API v2 using the default HTTP client and a 5-second timeout. No API key is set by default; free-tier rate limits apply until one is provided via WithAPIKey.
func (Client) CompanyName ¶
func (c Client) CompanyName(mac string) (ResponseVendorName, error)
CompanyName queries the lightweight company-name endpoint of the maclookup.app API and returns just the vendor name associated with the given MAC address or prefix.
mac may be supplied in any common notation (colon-separated, dash-separated, dot-separated, or plain hex). Only the OUI/MA prefix portion is used.
Possible error types: *HTTPClientError, *BadAPIRequest, *BadAPIKey, *RateLimitsExceeded.
Example ¶
//Prevent rate limits error
time.Sleep(time.Millisecond * 550)
client := New()
r, err := client.CompanyName("000000")
fmt.Println(err)
fmt.Printf("%s", r.Company)
Output: <nil> XEROX CORPORATION
Example (NotFound) ¶
//Prevent rate limits error
time.Sleep(time.Millisecond * 550)
client := New()
r, err := client.CompanyName("010000")
fmt.Println(err)
fmt.Printf("%s\n", r.Company)
fmt.Printf("%t", r.Found)
Output: <nil> false
func (Client) Lookup ¶
func (c Client) Lookup(mac string) (ResponseMACInfo, error)
Lookup queries the maclookup.app API for full vendor registration data associated with the given MAC address or prefix.
mac may be supplied in any common notation (colon-separated, dash-separated, dot-separated, or plain hex). Only the OUI/MA prefix portion is used.
Possible error types: *HTTPClientError, *BadAPIRequest, *BadAPIKey, *RateLimitsExceeded, *BadAPIResponse.
Example ¶
//Prevent rate limits error
time.Sleep(time.Millisecond * 550)
client := New()
r, err := client.Lookup("000000")
fmt.Println(err)
fmt.Printf("%+v", r.MACInfo)
Output: <nil> {Found:true MacPrefix:000000 Company:XEROX CORPORATION Address:M/S 105-50C, WEBSTER NY 14580, US Country:US BlockStart:000000000000 BlockEnd:000000FFFFFF BlockSize:16777215 BlockType:MA-L Updated:2015-11-17 IsRand:false IsPrivate:false}
Example (NotFound) ¶
//Prevent rate limits error
time.Sleep(time.Millisecond * 550)
client := New()
r, err := client.Lookup("010000")
fmt.Println(err)
fmt.Printf("%+v", r.MACInfo)
Output: <nil> {Found:false MacPrefix: Company: Address: Country: BlockStart: BlockEnd: BlockSize:0 BlockType: Updated: IsRand:false IsPrivate:false}
func (*Client) WithAPIKey ¶
WithAPIKey sets the API key used for authenticated requests. Obtain a key at https://maclookup.app/api-v2/plans.
func (*Client) WithPrefixURI ¶
WithPrefixURI replaces the default API base URL (https://api.maclookup.app). Useful for testing or when routing through a proxy. If the supplied string starts with an IP address (and no explicit scheme), http:// is used; otherwise https:// is added when no scheme is present.
func (*Client) WithTimeout ¶
WithTimeout overrides the per-request HTTP timeout (default: 5 s).
type CompanyInfo ¶
CompanyInfo contains the vendor name associated with a MAC prefix as returned by the lightweight company-name endpoint. Found is false when the prefix is not in the database. IsPrivate is true when the block is marked as a private address range. Company holds the registrant name; it is empty when Found is false or IsPrivate is true.
type HTTPClientError ¶
type HTTPClientError struct {
Err error
}
HTTPClientError wraps a low-level HTTP or network error (e.g. connection refused, context deadline exceeded, or an unexpected HTTP status code).
func (*HTTPClientError) Error ¶
func (c *HTTPClientError) Error() string
Error implements the error interface.
func (*HTTPClientError) Unwrap ¶
func (c *HTTPClientError) Unwrap() error
Unwrap returns the underlying error, enabling errors.Is / errors.As traversal.
type MACInfo ¶
type MACInfo struct {
Found bool
MacPrefix string
Company string
Address string
Country string
BlockStart string
BlockEnd string
BlockSize int
BlockType string
Updated string
IsRand bool
IsPrivate bool
}
MACInfo contains the vendor registration data associated with a MAC prefix. Found is false when the prefix is not present in the database; in that case all other string and numeric fields are zero values.
type RateLimit ¶
RateLimit carries the rate-limit metadata returned by the API on every response. Limit is the maximum number of requests allowed in the current window. Remaining is how many requests are still available. Reset is the UTC time at which the counter resets.
type RateLimitsExceeded ¶
RateLimitsExceeded is returned when the API responds with HTTP 429. Limit holds the maximum request quota for the current window and Reset indicates when the counter will be reset.
func (*RateLimitsExceeded) Error ¶
func (c *RateLimitsExceeded) Error() string
Error implements the error interface.
type ResponseMACInfo ¶
ResponseMACInfo is the full response returned by Client.Lookup. It embeds RateLimit (current quota information) and MACInfo (vendor data). RespTime records the total round-trip duration of the HTTP request.
type ResponseVendorName ¶
type ResponseVendorName struct {
RespTime time.Duration
RateLimit
CompanyInfo
}
ResponseVendorName is the response returned by Client.CompanyName. It embeds RateLimit (current quota information) and CompanyInfo (vendor name). RespTime records the total round-trip duration of the HTTP request.
Source Files
Directories