Poe-trade-fetch NPM

PoE Trade Fetch Documentation

This document provides an in-depth overview of the PoE Trade Fetch library, which you can use to interact with the Path of Exile (PoE) trading API.

Overview

PoE Trade Fetch is a JavaScript library designed to interact with the PoE in-game trading platform API. It simplifies the process of fetching item data, handling rate limits, and parsing search results in a structured way.

Features

API Integration: Easily connect to the PoE Trade API.
Rate Limit Handling: Built-in support for managing request delays to avoid rate limiting.
Flexible Query: Customize searches based on item attributes.
Multiple Request Types: Separate methods for initial searches and detailed follow-up requests.

Prerequisites

Node.js version 12 or above.
A valid POESESSID (optional, increases request limit).
Basic knowledge of JavaScript and asynchronous programming.

Installation

You can install the package using npm:

npm install poe-trade-fetch

Usage

Initialization

First, import the necessary components and initialize the library with your settings:

import { 
    LEAGUES_NAMES, 
    REALMS, 
    PoeTradeFetch, 
    RequestBodyType,
    RATE_LIMIT_STATE_KEYS
} from 'poe-trade-fetch';

const poeTradeFetch = PoeTradeFetch.createInstance({
  leagueName: LEAGUES_NAMES.Current,  // Default: 'Standard'
  userAgent: 'My PoE App  your@mail.kek',
  realm: REALMS.pc,                   // Default: pc
  POESESSID: 'Your POESESSID',         // Optional: for increased request rate
  useRateLimitDelay: true             // Default: true 
});
await poeTradeFetch.update();

Making Requests

First Request

Perform an initial search request using your custom query:

const RequestBody: RequestBodyType = {
  query: {
    status: { option: 'online' },
    name: 'Prismweave',
    type: 'Rustic Sash',
    stats: [{ type: 'and', filters: [], disabled: false }],
  },
  sort: { price: 'asc' },
};

const { result, id } = await poeTradeFetch.firsRequest(RequestBody);

// Ensure a maximum of 10 identifiers, as PoE API limits the request
const identifiers = result.length > 10 ? result.slice(0, 10) : result;

Second Request

Fetch detailed trade data for the listed item identifiers:

const { result: secondResult } = await poeTradeFetch.secondRequest(identifiers, id);
console.log('Trade Data Items:', secondResult);

// Example: accessing price details
const numberPrice = secondResult[0].listing.price.amount;
const currencyPrice = secondResult[0].listing.price.currency;

API Reference

PoeTradeFetch(options)
Initializes the API client. Options include:
- leagueName (default: LEAGUES_NAMES.Standard)
- userAgent
- realm (default: REALMS.pc)
- POESESSID (optional)
update()
Fetches necessary metadata and updates the internal state.
firsRequest(RequestBodyType)
Executes the initial search request. Returns object with:
- id: identifier for the request
- result: list of item identifiers
secondRequest(identifiers, id)
Fetches detailed trade information based on identifiers and request ID.
httpRequest.getWaitTime(key)
Returns the required delay time for the next request based on the rate limiting key.

Troubleshooting

Rate Limit Errors:
Ensure you implement the proper delay between requests. If you experience rate limiting issues, consider adjusting your request intervals or using a valid POESESSID.
Invalid Query Responses:
Double-check your query parameters. Consult the PoE Trade API documentation for valid parameter options.