README.md

gw2-api.com

Proxy-layer server for the official GuildWars 2 API.

---

NO LONGER MAINTAINED, MAY BREAK AT ANY POINT

In the old days, before the official API, you could get item and price data by requesting a session token from the official login page and then using the urls the tradingpost used ingame as a unofficial API. This project originated when I wanted to this data for a tradingpost section on gw2efficiency.com, but I was not satisfied with the existing solutions (mainly because of cache time, update frequency and data format).

Now, most of this code is integrated into the internal API of gw2efficiency.com directly and this code is not longer maintained (even tho it may remain usable). This repository is mainly online for historical reasons.

---

Install

• Requirements:
  • MongoDB as the database layer (use wiredTiger!)
  • Redis for the priority job queue
  • A process manager to keep the processes running, in this example pm2
  • (Optional) Some sort of caching like Varnish

# Clone the repository
git clone https://github.com/gw2efficiency/gw2-api.com
cd gw2-api.com/

# Install the dependencies and build all files
npm install
npm run build

# Build the initial database using the cli tool
node build/bin/cli.js full-rebuild

# Start the job worker process
pm2 start build/bin/worker.js --name="gw2api-worker"

# Start the job scheduling
pm2 start build/bin/scheduler.js --name="gw2api-scheduler"

# Start the job monitoring interface (port 3000)
pm2 start build/bin/kue.js --name="gw2api-kue"

# Start a server cluster for API routes (port 8080)
pm2 start build/bin/server.js --name="gw2api-server" -i 3

Logs for all processes will be written in ~/.pm2/logs.

CLI

You can fire off any jobs using the included cli tool, either directly in the cli process or as usual as a queued job, which gets processed by the worker processes:

node build/bin/cli.js <job-name> # Execute job in this process
node build/bin/cli.js <job-name> -q # Push the job in the queue

The following jobs exist:

• full-rebuild (clear the database and execute all jobs)
• item-list (get all items)
• item-prices (update the item prices)
• item-values (calculate the item values)
• recipe-list (get all recipes)
• crafting-prices (calculate the crafting prices)
• skin-list (get all skins)
• skin-prices (calculate all skin prices)
• gem-price-history (get the gem price history)
• item-last-known-prices (get the last known sell prices, if they are missing)

Running in production

When running the servers in production, use the NODE_ENV environment variable to set the environment to production. Note that this will load the config/environment.production.js configuration, so you will have to copy the default config/environment.js and make sure the values match your setup.

NODE_ENV=production pm2 start build/bin/worker.js --name="gw2api-worker"
NODE_ENV=production pm2 start build/bin/scheduler.js --name="gw2api-scheduler"
NODE_ENV=production pm2 start build/bin/kue.js --name="gw2api-kue"
NODE_ENV=production pm2 start build/bin/server.js --name="gw2api-server" -i 3

Tests

Note: Requires a running instance of mongodb and will execute on a test database. Also requires a running instance of redis and will flush all existing jobs.

npm test

Endpoints

• /item/:id
• /items/:ids
• /items/all
• /items/all-prices
• /items/all-values
• /items/autocomplete
• /items/by-name
• /items/by-skin
• /items/by-crafting-profit
• /items/query
• /items/categories
• /skins/resolve
• /skins/prices
• /recipe/nested/:ids
• /gems/history

/item/:id

This endpoint returns a single item.

Parameters

• id: An item id, either in the url or as a GET/POST parameter
• lang (optional): The requested language (defaults to english)

{
  "id": 123,
  "name": "Zho's Mask",
  "description": "Some item description",
  "skins": [123],
  "level": 80,
  "rarity": 5,
  "tradable": true,
  "image": "https://...",
  "category": [
    0,
    3
  ],
  "vendor_price": 330,
  "buy": {
    "quantity": 94,
    "price": 4852,
    "last_change": {
      "time": "2015-06-09T05:55:44+0000",
      "quantity": 1,
      "price": 1
    }
  },
  "sell": {
    "quantity": 378,
    "price": 7635,
    "last_change": {
      "time": "2015-06-09T00:04:59+0000",
      "quantity": 16,
      "price": -140
    }
  },
  "crafting": {
    "buy": 1337,
    "sell": 4242
  },
  "last_update": "2015-06-09T05:55:44+0000"
}

/items/:ids

This endpoint returns an array of items.

Parameters

• ids: An array or a comma separated list of one or more item ids, either in the url or as a GET/POST parameter
• lang (optional): The requested language (defaults to english)

[
  {
    "id": 123, 
    "name": "Zho's Mask", 
    // like /item/:id ...
  },
  // ...
]

/items/all

This endpoint returns an array of all tradable items.

Parameters

• lang (optional): The requested language (defaults to english)

[
  {
    "id": 123, 
    "name": "Zho's Mask", 
    // like /item/:id ...
  },
  // ...
]

/items/all-prices

This endpoint returns an array of all tradable item ids with their prices.

[
  {
    "id": 123, 
    "price": 1337
  },
  // ...
]

/items/all-values

This endpoint returns an array of all items with their value. If you want to learn more about how the value of an item is calculated, read more here.

[
  {
    "id": 456, 
    "value": 42
  },
  // ...
]

/items/autocomplete

This endpoint returns an array of up to 20 items best matching the search query.

Parameters

• q: The term to search for in the item names
• lang (optional): The requested language (defaults to english)

[
  {
    "id": 123,
    "name": "Zho's Mask",
    "level": 80,
    "rarity": 5,
    "image": "https://..."
  },
  // ...
]

/items/by-name

This endpoint returns an array of all items matching the name exactly (case-sensitive!).

Parameters

• names: An array or a comma separated list of one or more item names, as a GET/POST parameter
• lang (optional): The requested language (defaults to english)

[
  {
    "id": 123, 
    "name": "Zho's Mask", 
    // like /item/:id ...
  },
  // ...
]

/items/by-skin

This endpoint returns an array of all item ids matching the skin id.

Parameters

• skin_id: An skin id, as a GET/POST parameter

[
  123,
  124,
  125,
  // ...
]

/items/by-crafting-profit

This endpoint returns an array of all craftable items, ordered by crafting profit.

Parameters

• page: The page number to enumerate through the pages (50 items per page)

{
  totalResults: 1234,
  results: [
    {
      "id": 123, 
      "name": "Zho's Mask", 
      // like /item/:id ...
    },
    // ...
  ]
}

/items/query

This endpoint returns all items matching the query.

PLEASE DO NOT USE THIS HEAVILY Please note that this endpoint is not as optimized as the others, since it should never be used directly user facing. This is supposed to be only used for server-side tasks that run every once in a while.

Parameters

• categories: Semicolon separated list of category ids that the queried items must match
• rarities: Semicolon separated list of rarities that the queried items must match
• craftable: If set to any value, queried items must be craftable
• exclude_name: Queried items must exclude this string in their name
• include_name: Queried items must include this string in their name
• output: If set, returns a object with price information across all matches instead of item ids

// output not set
[
  123,
  124,
  125,
  // ...
]

// output "prices"
{
  "buy": {
    "min": 123,
    "avg": 456,
    "max": 789
  },
  "sell": {
    "min": 123,
    "avg": 456,
    "max": 789
  }
}

/items/categories

This endpoint returns an array of the item categories that are used as identifiers for the other item endpoints.

{
  "Armor": [
    0,
    {
      "Boots": 0,
      "Coat": 1,
      "Gloves": 2,
      "Helm": 3,
      "HelmAquatic": 4,
      "Leggings": 5,
      "Shoulders": 6
    }
  ],
  "Back": [
    1
  ],
  "Bag": [
    2
  ],
  // ...
}

/skins/resolve

This endpoint returns a list of all skin ids with their respective item ids.

{
  "1": [2902,2903 /* ... */],
  "18":[2534,2535,2557 /* ... */],
  // ...
}

/skins/prices

This endpoint returns a list of all buyable skin ids with their respective cheapest value. If you want to learn more about how the value of an item is calculated, read more here.

{
  "1": 123,
  "18": 456,
  // ...
}

/recipe/nested/:ids

This endpoint returns nested recipes for the specified items (if a recipe exists for them). All components that can be crafted include their respective recipe and subcomponents.

Parameters

• ids: An array or a comma separated list of one or more item ids, either in the url or as a GET/POST parameter

[
  {
    "id": 31083,
    "output": 1,
    "quantity": 1,
    "components": [
      {
        "id": 20852,
        "quantity": 1
      },
      {
        "id": 13243,
        "quantity": 5,
        "output": 1,
        "components": [/* ... */]
      },
      // ...
    ]
  }
  // ...
]

/gems/history

This endpoint returns price history data for gold to gems conversion.

{
  "gold_to_gem": [
    [
      1347314400000, // timestamp in ms
      2747 // Conversion price (27s 47c per bought gem)
    ],
    [1347400800000,2735],
    // ...
  ],
  "gem_to_gold": [
    [
      1347314400000, // timestamp in ms
      1965 // conversion price (19s 65c per sold gem)
    ],
    [1347400800000,1956],
    // ...
  ]

Licence

AGPL