Skip to content

Aluquot/gw2api

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

gw2treasures/gw2api

version license Travis Coverage

PHP wrapper for the Guild Wars 2 API.

Features

  • Support for all v2 endpoints (including authenticated)
  • Parallel requests for pagination and bulk expansion

Requirements

  • PHP >= 5.4

Setup

Using composer (recommended)

composer require gw2treasures/gw2api

If you haven't included composers autoloader yet, you will have to add this before being able to use the GW2 API Wrapper.

include 'vendor/autoload.php';

Using the gw2api.phar archive

You need to download the latest gw2api.phar and the guzzle.phar of the latest 5.x version of the guzzle library and place both files in your project directory. Now you can include both files to start using the GW2 API wrapper.

include __DIR__ .  '/gw2api.phar';
include __DIR__ .  '/guzzle.phar';

Examples

// create new api instance
$api = new \GW2Treasures\GW2Api\GW2Api();

// get all worlds
$worlds = $api->worlds()->all();

// get some happy quaggans
$quaggans = $api->quaggans()->many([ 'cheer', 'party' ]);

// get item details in german
$ektoplasmakugel = $api->items()->lang('de')->get(19721);

// search recipes
$recipes = $api->recipes()->search()->input(46746);

// get all character names
$characters = $api->characters('api_key')->ids();

// get 10 recently bought items
$recentlyBought = $api->commerce()->transactions('api_key')->history()->buys()->page(0, 10);

Usage

For all examples it is assumed that you have a variable $api = new GW2Api().

Endpoint Overview

API Endpoint Class
Instance
Flags
/v2/account Account\AccountEndpoint
GW2Api::account()
🔒
/v2/account/bank Account\BankEndpoint
GW2Api::account()->bank()
🔒
/v2/account/dyes Account\DyeEndpoint
GW2Api::account()->dyes()
🔒
/v2/account/materials Account\MaterialEndpoint
GW2Api::account()->materials()
🔒
/v2/account/skins Account\SkinEndpoint
GW2Api::account()->skins()
🔒
/v2/account/wallet Account\WalletEndpoint
GW2Api::account()->wallet()
🔒
/v2/build Build\BuildEndpoint
GW2Api::build()
/v2/characters Character\CharacterEndpoint
GW2Api::characters()
🔒📦
/v2/characters/:id/equipment Character\EquipmentEndpoint
GW2Api::characters()->equipment()
🔒
/v2/characters/:id/inventory Character\InventoryEndpoint
GW2Api::characters()->inventory()
🔒
/v2/characters/:id/recipes disabled 🔒🚫
/v2/characters/:id/specializations Character\SpecializationEndpoint
GW2Api::characters()->specializations()
🔒
/v2/colors Color\ColorEndpoint
GW2Api::colors()
📦🌏
/v2/commerce/exchange Commerce\ExchangeEndpoint
GW2Api::commerce()->exchange()
/v2/commerce/listings Commerce\ListingEndpoint
GW2Api::commerce()->listings()
📦
/v2/commerce/prices Commerce\PriceEndpoint
GW2Api::commerce()->prices()
📦
/v2/commerce/transactions Commerce\Transaction\TransactionEndpoint
GW2Api::commerce()->transactions()
🔒📄
/v2/continents Continent\ContinentEndpoint
GW2Api::continents()
📦🌏
/v2/currencies Currency\CurrencyEndpoint
GW2Api::currencies()
📦🌏
/v2/events disabled 🌏🚫
/v2/events-state disabled 🚫
/v2/files File\FileEndpoint
GW2Api::files()
📦
/v2/guild/:id disabled 🚫
/v2/guild/:id/inventory disabled 🔒🚫
/v2/guild/:id/log disabled 🔒🚫
/v2/guild/:id/members disabled 🔒🚫
/v2/guild/:id/ranks disabled 🔒🚫
/v2/guild/permissions disabled 🔒🌏🚫
/v2/guild/upgrades disabled 🔒🌏🚫
/v2/items Item\ItemEndpoint
GW2Api::items()
📦🌏
/v2/leaderboards disabled 🚫
/v2/maps Map\MapEndpoint
GW2Api::maps()
📦🌏
/v2/materials Material\MaterialEndpoint
GW2Api::materials()
📦🌏
/v2/pvp/games Pvp\GameEndpoint
GW2Api::pvp()->games()
🔒📦
/v2/pvp/stats Pvp\StatsEndpoint
GW2Api::pvp()->stats()
🔒
/v2/quaggans Quaggan\QuagganEndpoint
GW2Api::quaggans()
📦
/v2/recipes Recipe\RecipeEndpoint
GW2Api::recipes()
📦
/v2/recipes/search Recipe\SearchEndpoint
GW2Api::recipes()->search()
/v2/skills disabled 🚫
/v2/skins Skin\SkinEndpoint
GW2Api::skins()
📦🌏
/v2/specializations Specialization\SpecializationEndpoint
GW2Api::specializations()
📦🌏
/v2/tokeninfo Tokeninfo\TokeninfoEndpoint
GW2Api::tokeninfo()
🔒
/v2/traits Traits\TraitEndpoint
GW2Api::traits()
📦🌏
/v2/worlds World\WorldEndpoint
GW2Api::worlds()
📦🌏
/v2/wvw/matches disabled 🚫
/v2/wvw/objectives WvW\ObjectiveEndpoint
GW2Api::wvw()->objectives()
📦🌏

† Not FQN, all endpoints are in the namespace \GW2Treasures\GW2Api\V2\Endpoint
‡ Flags:
    🔒AuthenticatedEndpoint
    📦BulkEndpoint
    🌏LocalizedEndpoint
    📄PaginatedEndpoint
    🚫Disabled in the API

Abstract Endpoints

AuthenticatedEndpoint

\GW2Treasures\GW2Api\V2\Authentication\IAuthenticatedEndpoint (source)

All endpoints requiring authentication implement the interface IAuthenticatedEndpoint. Throws AuthenticationException and InvalidPermissionsException.

BulkEndpoint

\GW2Treasures\GW2Api\V2\Bulk\IBulkEndpoint (source)

All endpoints supporting bulk expansion implement the interface IBulkEndpoint. Extends PaginatedEndpoint. Throws PageOutOfRangeException.

Methods
  • all():array Get all entries.
    If the endpoint doesn't support ?ids=all this falls back to PaginatedEndpoint::all().
  • ids():int[]|string[] Get all ids.
  • get(int|string $id):mixed Get a single entry by id.
  • many(int[]|string[] $ids):array Get multiple entries by id.
  • IPaginatedEndpoint::page(int $page, [int $size]):array Get a specific page of the endpoint.
  • IPaginatedEndpoint::batch([int $parallelRequests], Closure $callback):void Get all entries in multiple small batches. The callback gets called with new entries until all entries have been processed.
    Signature of the callback: function(array $entries):void.
Example
$api->items()->all();
// => returns array with all items

$api->items()->ids();
// => returns array with all item ids

$api->items()->get(1);
// => returns item with id 1

$api->items()->many([1,2,3]);
// => returns items with ids 1, 2 and 3

LocalizedEndpoint

\GW2Treasures\GW2Api\V2\Localization\ILocalizedEndpoint (source)

All endpoints supporting localization implement the interface ILocalizedEndpoint. Defaults to en. Throws InvalidLanguageException.

Methods
  • lang(string $lang):$this Change the language of the endpoint.
Example
$api->items()->lang('de')->get(1)
// => returns german item 1

PaginatedEndpoint

\GW2Treasures\GW2Api\V2\Pagination\IPaginatedEndpoint (source)

All endpoints supporting pagination implement the interface IPaginatedEndpoint. Throws PageOutOfRangeException.

Methods
  • all():array Get all entries.
    Requests all pages of this endpoint in parallel and returns the merged result.
  • page(int $page, [int $size]):array Get a page of entries. The $size defaults to the maximum page size (200 for most endpoints).
  • batch([int $parallelRequests], Closure $callback):void Get all entries in multiple small batches. The callback gets called with new entries until all entries have been processed.
    Signature of the callback: function(array $entries):void.

Example

$api->items()->all();
// => returns all items

$api->items()->page(0, 10);
// => returns first page of 10 items

$api->items()->batch(function($items) {
    // $items contains items of current batch.
    // gets called multiple times with different items untill all items have been processed.
});

Exceptions

ApiException

\GW2Treasures\GW2Api\Exception\ApiException (source)

Gets thrown by all endpoints when the API returns an error. Extends \Exception.

Methods
  • getResponse():ResponseInterface The response that was returned by the API.
Example
try {
    $api->items()->get('invalid item id');
} catch(ApiException $exception) {
    $exception->getMessage() === "no such id"
}

AuthenticationException

\GW2Treasures\GW2Api\V2\Authentication\Exception\AuthenticationException (source)

Gets thrown by AuthenticatedEndpoints when the endpoint needs authentication but no API key was specified or the API key was invalid. Extends ApiException.

Example
try {
    $api->account('INVALID_API_KEY')->get();
} catch(AuthenticationException $exception) {
    $exception->getMessage() === "invalid key"
}

InvalidPermissionsException

\GW2Treasures\GW2Api\V2\Authentication\Exception\InvalidPermissionsException (source)

Gets thrown by AuthenticatedEndpoints when the API key is missing permissions to access the endpoint. Extends AuthenticationException.

Methods
  • getMissingScope():string The permission that was missing to access the endpoint.
Example
try {
    $api->characters('API_KEY_WITHOUT_CHARACTERS_SCOPE')->get();
} catch(InvalidPermissionsException $exception) {
    $exception->getMessage() === "requires scope characters"
    $exception->getMissingScope() === "characters"
}

InvalidLanguageException

\GW2Treasures\GW2Api\V2\Localization\Exception\InvalidLanguageException (source)

Gets thrown by LocalizedEndpoints when the API responds with a different language than requested. Extends ApiException.

Methods
  • getRequestLanguage():string The requested language.
  • getResponseLanguage():string The language the API responded with.
Example
try {
    $api->items()->lang('invalid')->get(1);
} catch(InvalidLanguageException $exception) {
    $exception->getMessage() === "Invalid language (expected: invalid; actual: en)"
    $exception->getRequestLanguage() === "invalid"
    $exception->getResponseLanguage() === "en"
}

PageOutOfRangeException

\GW2Treasures\GW2Api\V2\Pagination\Exception\PageOutOfRangeException (source)

Gets thrown by PaginatedEndpoints when requesting a page that doesn't exist. Extends ApiException.

Example
try {
    $api->items()->page(9001);
} catch(PageOutOfRangeException $exception) {
    $exception->getMessage() === "page out of range. Use page values 0 - 826."
}

Endpoints

/v2/account

\GW2Treasures\GW2Api\V2\Endpoint\Account\AccountEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods
Example
$api->account('API_KEY')->get();
// => { id: "account-guid", name: "Lawton.1234", … }

/v2/account/bank

\GW2Treasures\GW2Api\V2\Endpoint\Account\BankEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods
  • get():array Get account bank.
Example
$api->account('API_KEY')->bank()->get();
// => [ null, { id: 46774, slot: 1, count: 1 }, … ]

/v2/account/dyes

\GW2Treasures\GW2Api\V2\Endpoint\Account\DyeEndpoint (source)

The ColorEndpoint can be used to look up the skins used by this endpoint. Implements 🔒AuthenticatedEndpoint.

Methods
  • get():array Get unlocked dyes.
Example
$api->account('API_KEY')->dyes()->get();
// => [ 8, 12, 14, 17, … ]

/v2/account/materials

\GW2Treasures\GW2Api\V2\Endpoint\Account\MaterialEndpoint (source)

The MaterialEndpoint can be used to get the categories used by this endpoint. Implements 🔒AuthenticatedEndpoint.

Methods
  • get():array Get account material storage.
Example
$api->account('API_KEY')->materials()->get();
// => [ { id: 19699, category: 5, count: 250 }, … ]

/v2/account/skins

\GW2Treasures\GW2Api\V2\Endpoint\Account\SkinEndpoint (source)

The SkinEndpoint can be used to look up the skins used by this endpoint. Implements 🔒AuthenticatedEndpoint.

Methods
  • get():array Get unlocked skins.
Example
$api->account('API_KEY')->skins()->get();
// => [ 1, 2, 3, 4, … ]

/v2/account/wallet

\GW2Treasures\GW2Api\V2\Endpoint\Account\WalletEndpoint (source)

The CurrencyEndpoint can be used to look up the currencies used by this endpoint. Implements 🔒AuthenticatedEndpoint.

Methods
  • get():array Get the account wallet.
Example
$api->account('API_KEY')->wallet()->get();
// => [ { id: 1, value: 234885 }, … ]

/v2/build

\GW2Treasures\GW2Api\V2\Endpoint\Build\BuildEndpoint (source)

Methods
  • get():int Gets the current build id.
Example
$api->build()->get();
// => 50430

/v2/characters

\GW2Treasures\GW2Api\V2\Endpoint\Character\CharacterEndpoint (source)

Implements 🔒AuthenticatedEndpoint and 📦BulkEndpoint.

Methods
Example
$api->characters('API_KEY')->get('Character Name');
// => { name: "Hello", race: "Human", … }

/v2/characters/:id/equipment

\GW2Treasures\GW2Api\V2\Endpoint\Character\EquipmentEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods
  • get():array Gets the characters equipment.
Example
$api->characters('API_KEY')->equipment('Character Name')->get();
// => [ { id: 6472, slot: "Coat" }, … ]

/v2/characters/:id/inventory

\GW2Treasures\GW2Api\V2\Endpoint\Character\InventoryEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods
  • get():array Gets the characters inventory.
Example
$api->characters('API_KEY')->inventory('Character Name')->get();
// => [ { id: 8941, size: 4 inventory: [ null, { id: 32134, count: 1 }, … ] }, … ]

/v2/characters/:id/specializations

\GW2Treasures\GW2Api\V2\Endpoint\Character\SpecializationEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods
  • get():array Gets the characters specializations.
Example
$api->characters('API_KEY')->specializations('Character Name')->get();
// => { pve: [ { id: 41, traits: [232, 214, 226] }, … ], … }

/v2/colors

\GW2Treasures\GW2Api\V2\Endpoint\Color\ColorEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->colors()->lang('de')->all();
// => [ { id: 1, name: "Farbentferner", base_rgb: [128,26,26], … }, … ]

/v2/commerce/exchange

\GW2Treasures\GW2Api\V2\Endpoint\Commerce\ExchangeEndpoint (source)

Methods
  • gems(int $quantity):mixed Current gem to coins exchange rate.
  • coins(int $quantity):mixed Current coins to gems exchange rate.
Example
$api->commerce()->exchange()->gems(50);
// => { coins_per_gem: 1211, quantity: 60579 }

/v2/commerce/listings

\GW2Treasures\GW2Api\V2\Endpoint\Commerce\ListingEndpoint (source)

Implements 📦BulkEndpoint.

Methods
Example
$api->commerce()->listings()->get(24);
// => { id: 24, buys: [ { listings: 1, unit_price: 186, quantity: 250 }, … ] }

/v2/commerce/prices

\GW2Treasures\GW2Api\V2\Endpoint\Commerce\PriceEndpoint (source)

Implements 📦BulkEndpoint.

Methods
Example
$api->commerce()->prices()->get(24);
// => { id: 24, buys: { quantity: 20854, unit_price: 186 }, sells: { quantity: 9787, unit_price: 340 } }

/v2/commerce/transactions

\GW2Treasures\GW2Api\V2\Endpoint\Commerce\Transaction\TransactionEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods

/v2/commerce/transactions/:type

\GW2Treasures\GW2Api\V2\Endpoint\Commerce\Transaction\TypeEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods

/v2/commerce/transactions/:type/:list

\GW2Treasures\GW2Api\V2\Endpoint\Commerce\Transaction\ListEndpoint (source)

Implements 🔒AuthenticatedEndpoint and 📄PaginatedEndpoint.

Methods
Example
$api->commerce()->transactions('API_KEY')->current()->sells()->all();
// => [ { id: 1999, item_id: 19699, price: 1004, quantity: 20, created: "2014-12-15T14:43:36+00:00" }, … ]

/v2/continents

\GW2Treasures\GW2Api\V2\Endpoint\Continent\ContinentEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->continents()->get(1);
// => { name: "Tyria", … }

/v2/currencies

\GW2Treasures\GW2Api\V2\Endpoint\Currency\CurrencyEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->currencies()->get(1);
// => { id: 1, name: "Coin", … }

/v2/continents/:id/floors

\GW2Treasures\GW2Api\V2\Endpoint\Continent\FloorEndpoint (source)

Implements 📦BulkEndpoint.

Methods
Example
$api->continents()->floors(1)->get(0);
// => { texture_dims: [ 32768, 32768 ], … }

/v2/files

\GW2Treasures\GW2Api\V2\Endpoint\File\FileEndpoint (source)

Implements 📦BulkEndpoint.

Methods
Example
$api->files()->ids();
// => [ "map_complete", "map_dungeon", … ]

/v2/items

\GW2Treasures\GW2Api\V2\Endpoint\Item\ItemEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->items()->ids();
// => [ 1, 2, 6, 11, 24, … ]

/v2/maps

\GW2Treasures\GW2Api\V2\Endpoint\Map\MapEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->maps()->get(15);
// => { id: 15, name: "Queensdale", … }

/v2/materials

\GW2Treasures\GW2Api\V2\Endpoint\Material\MaterialEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->materials()->lang('es')->all();
// => [ { id:5, name: "Materiales de cocina", items: [ 12134, … ] }, … ]

/v2/pvp/games

\GW2Treasures\GW2Api\V2\Endpoint\Pvp\GameEndpoint (source)

Implements 🔒AuthenticatedEndpoint and 📦BulkEndpoint.

Methods
Example
$api->pvp('API_KEY')->games()->get('A9F9FD97-F114-4F97-B2CA-5E814DF0340E');
// => { id: "A9F9FD97-F114-4F97-B2CA-5E814DF0340E", map_id: 795, … }

/v2/pvp/stats

\GW2Treasures\GW2Api\V2\Endpoint\Pvp\StatsEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods
  • get():mixed Get pvp stats.
Example
$api->pvp('API_KEY')->stats()->get();
// => { pvp_rank: 57, aggregate: { wins: 343, … }, … }

/v2/quaggans

\GW2Treasures\GW2Api\V2\Endpoint\Quaggan\QuagganEndpoint (source)

Implements 📦BulkEndpoint.

Methods
Example
$api->quaggans()->many(['cheer', 'party']);
// => [ { id: "cheer", url: "cheer.jpg" }, { id: "party", url: "party.jpg" } ]

/v2/recipes

\GW2Treasures\GW2Api\V2\Endpoint\Recipe\RecipeEndpoint (source)

Implements 📦BulkEndpoint.

Methods
Example
$api->recipes()->ids();
// => [ 1, 2, 3, 4, 5, … ]

/v2/recipes/search

\GW2Treasures\GW2Api\V2\Endpoint\Recipe\SearchEndpoint (source)

Methods
  • input(int $id):mixed Searches for recipes with $id as ingredient.
  • output(int $id):mixed Searches for recipes with $id as output.
Example
$api->recipes()->search()->input(43775);
// => [ 7259, 7260, 7261, 7262, … ]

/v2/skins

\GW2Treasures\GW2Api\V2\Endpoint\Skin\SkinEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->skins()->get(1);
// => { name: "Chainmail Leggings", type: "Armor", … }

/v2/specializations

\GW2Treasures\GW2Api\V2\Endpoint\Specialization\SpecializationEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->specializations()->get(1);
// => { id: 1, name: "Dueling", profession: "Mesmer", … }

/v2/tokeninfo

\GW2Treasures\GW2Api\V2\Endpoint\Tokeninfo\TokeninfoEndpoint (source)

Implements 🔒AuthenticatedEndpoint.

Methods
  • get():mixed Get info about the used api key.
Example
$api->tokeninfo('API_KEY')->get();
// => { id: "API_KEY", name: "key name", permissions: [ "account", … ] }

/v2/traits

\GW2Treasures\GW2Api\V2\Endpoint\Traits\TraitEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->traits()->get(214);
// => { id: 214, tier:2, name: "Aeromancer's Training", … }

/v2/worlds

\GW2Treasures\GW2Api\V2\Endpoint\World\WorldEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->worlds()->all();
// => [ { id: 1001, name: "Anvil Rock" }, … ]

/v2/wvw/objectives

\GW2Treasures\GW2Api\V2\Endpoint\WvW\ObjectiveEndpoint (source)

Implements 📦BulkEndpoint and 🌏LocalizedEndpoint.

Methods
Example
$api->wvw()->objectives()->get('968-98');

// => { id: "968-98", name: "Wurm Tunnel", … }

License

MIT © 2015 gw2treasures.com

About

PHP wrapper for the Guild Wars 2 API

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 100.0%