Getting Started

Overview

Apinoa is one API for marketplace product data. Amazon, eBay, Shopify, Walmart and AliExpress answer in the same normalized schema, behind one key: the marketplace is a segment of the path, and everything else about a request stays the same. Image translation is available on the same key.

Quick Start

1. Create an Account

Sign up at apinoa.com and verify your email address.

2. Add Credit

There are no plans to choose, and signing up needs no card. You are billed per call from a prepaid balance, at the rate on the pricing page. Dashboard > Balance shows what is left and tops it up. To evaluate first, you can request $1 of free credit from the Free credit card on your dashboard.

3. Generate an API Key

Go to Dashboard > API Keys and create a new key. You can optionally set a prefix for easy identification.

# Your API key will look like this:
myapp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Store your API key securely. It is only shown once, at creation time. One key works for every marketplace.

4. Make Your First Request

Send the key in the x-api-key header:

curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" \
  -H "x-api-key: YOUR_API_KEY"

The same request can carry its parameters as a JSON body instead of a query string. The two are equivalent:

curl -X POST https://gateway.apinoa.com/v1/walmart/search \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"query": "wool socks", "priceMax": 30}'

const url = new URL("https://gateway.apinoa.com/v1/walmart/search");
url.searchParams.set("query", "wool socks");

const res = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" } });
const { success, data, error } = await res.json();
console.log(success ? data.items[0] : error);

5. Understand the Response

Every response uses the same envelope: success, then either data or error. A search returns a SearchResult inside data:

{
  "success": true,
  "data": {
    "marketplace": "walmart",
    "query": "wool socks",
    "page": { "index": 1, "size": 40, "total": 1000 },
    "items": [
      {
        "marketplace": "walmart",
        "id": "996425081",
        "title": "Merino Wool Hiking Socks, 3 Pack",
        "price": { "currency": "USD", "amount": 18.97 },
        "rating": { "average": 4.6, "count": 1204 },
        "inStock": true
      }
    ]
  }
}

price.amount is in decimal major units. An absent field means the marketplace did not say — it is never filled with a default, so an absent price is not zero.

If something goes wrong, the envelope carries an error code and message instead:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "brands: Unrecognized key(s) in object: 'brands'"
  }
}

6. Try Another Marketplace

Change the marketplace in the path. The key, the parameters and the response shape stay the same:

curl "https://gateway.apinoa.com/v1/ebay/search?query=wool+socks" -H "x-api-key: YOUR_API_KEY"
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: YOUR_API_KEY"

GET /v1/marketplaces lists every marketplace, the operations it supports, what each costs, and the JSON Schema of each operation's input.

Available APIs

Next Steps

• Marketplaces -- What is identical across marketplaces and what differs
• Response schema -- Every field you can receive
• Filters -- Price, brand, rating, condition and sort, on every marketplace
• Authentication -- API key authentication
• Versioning -- /v1, what the deprecated unversioned URLs still do, and the sunset date
• Error Codes -- Complete error reference