---
title: "Getting Started"
description: "Create an API key and run your first marketplace search in minutes."
---

## 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](https://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](/pricing). **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.

```bash
# 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:

```bash
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:

```bash
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}'
```

```javascript
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`](/docs/api-reference/marketplaces/response-schema) inside `data`:

```json
{
  "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:

```json
{
  "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:

```bash
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

| API | Endpoints | Description |
|-----|-----------|-------------|
| Marketplaces | `search`, `browse`, `categories`, `image-search`, `product`, `reviews` | Product data from Amazon, eBay, Shopify, Walmart and AliExpress in one schema |
| Image Translate | Translate, OCR, Supported Fonts | Replace text inside product images while preserving the original visual style |
| AliExpress | `search`, `product`, `categories`, `browse`, `image-search` | AliExpress product data |

## Next Steps

- [Marketplaces](/docs/api-reference/marketplaces) -- What is identical across marketplaces and what differs
- [Response schema](/docs/api-reference/marketplaces/response-schema) -- Every field you can receive
- [Filters](/docs/api-reference/marketplaces/filters) -- Price, brand, rating, condition and sort, on every marketplace
- [Authentication](/docs/authentication) -- API key authentication
- [Versioning](/docs/versioning) -- `/v1`, what the deprecated unversioned URLs still do, and the sunset date
- [Error Codes](/docs/errors) -- Complete error reference