Skip to content

Usage with Kotlin

Overview

PokeKotlin is a pure Kotlin library, so we can support all platforms that are supported by our dependencies. If we're missing one, please file an issue. We currently support:

  • Kotlin/JVM, including Android
  • Kotlin/JS for browser and Node
  • Kotlin/WASM for browser and Node
  • Kotlin/Native for Linux, Windows, macOS, iOS, tvOS, and watchOS

Installation with Gradle

This library is published via Maven Central, and snapshot builds of main are additionally available on GitHub Packages.

The latest release is v3.0.0-pre4. In your Gradle version catalog, add:

libs.versions.toml
[libraries]
pokekotlin = { module = "co.pokeapi.pokekotlin:pokekotlin", version = "3.0.0-pre4" }

Warning

The published documentation is for the latest release, and may not match the snapshot version. If using snapshots, always refer to the latest source code for the most accurate information.

First, follow GitHub's guide for authenticating to GitHub Packages. Your settings.gradle.kts should have something like this:

settings.gradle.kts
repositories {
  maven {
    url = uri("https://maven.pkg.github.com/pokeapi/pokekotlin")
    credentials {
      username = project.findProperty("gpr.user") as String? ?: System.getenv("GH_USERNAME")
      password = project.findProperty("gpr.key") as String? ?: System.getenv("GH_TOKEN")
    }
  }
}

The latest snapshot is v3.0.1-SNAPSHOT. In your Gradle version catalog, add:

libs.versions.toml
[libraries]
pokekotlin = { module = "co.pokeapi.pokekotlin:pokekotlin", version = "3.0.1-SNAPSHOT" }

In your Gradle build script, add:

build.gradle.kts
commonMain.dependencies {
  implementation(libs.pokekotlin)
}

Usage

For basic usage, use the global PokeApi instance:

fun main() = runBlocking {
  with(PokeApi) {
    runCatching {
      // Get a list of Pokémon species
      val list = getPokemonSpeciesList(0, 10)

      for (handle in list.results) {
        // Get each species by its handle
        val species = handle.get()
        println("Species: $species")
      }
    }.onFailure { e ->
      println("Error: ${e.message}")
    }
  }
}

Every PokeApi endpoint has a corresponding suspend fun method in the PokeApi instance. By default, the client will connect to the official https://pokeapi.co/ instance and cache results in memory. To customize the client, you can create your own instance of PokeApi.Custom.

For further details, see the Dokka API Reference.