Wizards API

A Kotlin Multiplatform library for accessing Wizards of the Coast Store & Event Locator API.

Disclaimer

This is an unofficial, reverse-engineered API client. Not endorsed by Wizards of the Coast. The API may change without notice. Use at your own risk.

Reverse Engineering

This library was built by reverse-engineering the official Wizards Store & Event Locator. For technical details including raw API requests, GraphQL queries, and response formats, see wizards_locator_api_notes.md.

Platforms

• JVM / Android
• iOS (x64, arm64, simulator)
• JavaScript (Browser, Node.js)

Installation

Gradle (Kotlin DSL)

repositories {
    mavenCentral()  // or mavenLocal() for local builds
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.devmugi:wizards-api:0.11.1")
        }

        // Platform-specific Ktor engines are required
        jvmMain.dependencies {
            implementation("io.ktor:ktor-client-cio:3.3.1")
        }
        androidMain.dependencies {
            implementation("io.ktor:ktor-client-cio:3.3.1")
        }
        iosMain.dependencies {
            implementation("io.ktor:ktor-client-darwin:3.3.1")
        }
        jsMain.dependencies {
            implementation("io.ktor:ktor-client-js:3.3.1")
        }
    }
}

JVM Only

dependencies {
    implementation("io.github.devmugi:wizards-api-jvm:0.11.1")
    implementation("io.ktor:ktor-client-cio:3.3.1")
}

JavaScript/Node.js (npm)

import api from '@devmugi/wizards-api';
const { WizardsLocatorJs } = api.devmugi.mtgcards.wizards.api.js;

const locator = new WizardsLocatorJs();
const stores = await locator.stores(49.8, 24.0);
locator.close();

Publishing Locally

# Maven Local (JVM/Android/iOS)
./gradlew :wizards-api:publishToMavenLocal

# npm (JavaScript/Node.js)
./gradlew :wizards-api:jsNodeProductionLibraryDistribution
cd wizards-api/build/dist/js/productionLibrary && npm link

Quick Start

val locator = WizardsLocator()

try {
    // Search for stores
    val stores = locator.stores(latitude = 50.94, longitude = 5.51)
    stores.forEach { println("${it.name} - ${it.distance}m") }

    // Search for events
    val events = locator.events(latitude = 50.94, longitude = 5.51)
    events.forEach { println("${it.title} - ${it.scheduledStartTime}") }
} finally {
    locator.close()
}

Configuration

val config = WizardsLocatorConfig(
    connectTimeoutMs = 30_000,
    enableLogging = true
)
val locator = WizardsLocator(config = config)

Property	Default	Description
apiUrl	Wizards GraphQL endpoint	API endpoint URL
connectTimeoutMs	10000	Connection timeout (ms)
requestTimeoutMs	10000	Request timeout (ms)
socketTimeoutMs	30000	Socket timeout (ms)
enableLogging	false	Enable HTTP logging
logLevel	INFO	Log verbosity (NONE, INFO, HEADERS, BODY, ALL)

Error Handling

The library throws specific exceptions:

• NetworkException - Connection failures, timeouts
• ApiException - HTTP 4xx/5xx errors (includes statusCode)
• DeserializationException - Response parsing failures
• IllegalArgumentException - Invalid parameters (latitude, longitude, etc.)

All exceptions extend WizardsApiException.

API Reference

stores()

suspend fun stores(
    latitude: Double,              // -90 to 90
    longitude: Double,             // -180 to 180
    maxMeters: Int = 10_000,
    pageSize: Int = 100,
    page: Int = 0,
    isPremium: Boolean = false
): List<Organization>

events()

suspend fun events(
    latitude: Double,
    longitude: Double,
    maxMeters: Int = 10_000,
    tags: List<String> = listOf("magic:_the_gathering"),
    sort: String = "date",
    sortDirection: String = "Asc",  // "Asc" or "Desc"
    startDate: String? = null,      // ISO 8601
    endDate: String? = null,
    page: Int = 0,
    pageSize: Int = 10
): List<Event>

For full API documentation, generate Dokka docs:

./gradlew :wizards-api:dokkaGenerateHtml
open wizards-api/build/dokka/html/index.html

Samples

Standalone sample projects are available in the samples/ directory:

Sample	Platform	Description
jvm/	JVM/Desktop	Kotlin + Gradle
android/	Android	Jetpack Compose
js-node-kotlin/	Node.js	Kotlin/JS + Gradle
js-node-npm/	Node.js	Pure JavaScript + npm

See samples/README.md for details.

Building

./gradlew :wizards-api:build
./gradlew :wizards-api:allTests

License

Magic: The Gathering is a trademark of Wizards of the Coast LLC. This project is not affiliated with or endorsed by Wizards of the Coast.