Java API Wrapper
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gradle
.idea
build/kotlin-build
gradle/wrapper
src
.DS_Store
.gitignore
LICENSE
README.md
build.gradle
gradlew
gradlew.bat
settings.gradle

README.md

api-java

A Java (Kotlin) wrapper for the IGDB.com Free Video Game Database API.

About IGDB

One of the principles behind IGDB.com is accessibility of data. We wish to share the data with anyone who wants to build cool videogame oriented websites, apps and services. This means that the information you contribute to IGDB.com can be used by other projects as well.

Thus, you are not only contributing to the value of this site but to thousands of other projects as well. We are looking forward to see what exciting game related projects you come up with. Happy coding!

More info here:

Libraries

This wrapper uses three libraries for http requests & JSON parsing.

Installation and setup

  • Maven
<repositories>
    <repository>
        <id>jitpack.io</id>
	<url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.igdb</groupId>
    <artifactId>api-java</artifactId>
    <version>2.0.0</version>
</dependency>
  • Gradle (Android)

    Step 1. Add this in your root build.gradle at the end of the repositories:

allprojects {
	repositories {
		...
		maven { url 'https://jitpack.io' }
	}
}

Step 2. Add the dependency

dependencies {
	compile 'com.github.igdb:api-java:2.0.0'
}

Step 3. Add internet permissions in the manifest

<uses-permission android:name="android.permission.INTERNET" />

Using your API key

  • Create a new APIWrapper Object by passing you 3Scale key, setting verison (Pro or standard), and set isDebug (prints queries)
IGDBWrapper wrapper = new IGDBWrapper("YOUR_API_KEY", Version.Standard, false);
val wrapper: IGDBWrapper = IGDBWrapper("YOUR_API_KEY")
// val wrapper: IGDBWrapper = IGDBWrapper("YOUR_API_KEY", Version.PRO, true) 
// Activates pro user access and dispalys query prints

Usage

All API endpoints are available as methods in the APIWrapper object. Each method has the following signature:

wrapper.endpoint(Parameters, OnSuccessCallback)

Arguments

  • Parameters - An object specifying the operations to be performed, ex. expander, filter, ordering etc. These Operations can be found in the API documentation under References: (https://igdb.github.io/api/references/)
  • onSuccessCallback - The callback is used to return to the previous method once the wrapper has retrieved the desired data from the API.

Example

  • Requesting games from API
// Java
IGDBWrapper wrapper = new IGDBWrapper("YOUR_API_KEY", Version.Standard, false);
Parameters params = new Parameters()
	.addFields("*")
	.addOrder("published_at:desc");
	
wrapper.games(params, new OnSuccessCallback(){
	@Override
        public void onSuccess(JSONArray result) {
        	// Do something with resulting JSONArray
        }

        @Override
        public void onError(Exception error) {
            	// Do something on error
        }
});
// Kotlin
val wrapper: IGDBWrapper = IGDBWrapper("YOUR_API_KEY")
val params: Parameters = Parameters()
	.addFields("*")
	.addOrder("published_at:desc")
	
wrapper.games(params, object: OnSuccessCallback{
        override fun onSuccess(JSONArray result) {
        	// Do something with resulting JSONArray
        }

        override fun onError(Exception error) {
            	// Do something on error
        }
})

/* The sent request will look like this:
https://api-2445582011268.apicast.io/games/?fields=*&order=published_at:desc */

The rest of the endpoints work similarly to the Games endpoint except for two cases presented bellow.

  • Requesting search from the API
// Java
IGDBWrapper wrapper = new IGDBWrapper("YOUR_API_KEY", Version.Standard, false);
Parameters params = new Parameters()
	.addSearch("searchQuery")
	.addFields("*")
	.addOrder("published_at:desc");

wrapper.search(Endpoint.GAMES, params, new onSuccessCallback(){
	@Override
        public void onSuccess(JSONArray result) {
        	// Do something with resulting JSONArray
        }

        @Override
        public void onError(Exception error) {
            	// Do something on error
        }
});
// Kotlin
val wrapper: IGDBWrapper = IGDBWrapper("YOUR_API_KEY")
val params: Parameters = Parameters()
	.addSearch("searchQuery")
	.addFields("*")
	.addOrder("published_at:desc")
	
wrapper.search(Endpoint.GAMES, params, object: OnSuccessCallback{
        override fun onSuccess(JSONArray result) {
        	// Do something with resulting JSONArray
        }

        override fun onError(Exception error) {
            	// Do something on error
        }
})

/* The sent request will look like this:
https://api-2445582011268.apicast.io/games/?search=searchQuery&fields=*&order=published_at:desc */

The search endpoint need an extra parameter, Endpoint, as you can search any endpoint for information.

  • Filtering a request result
// Java
IGDBWrapper wrapper = new IGDBWrapper("YOUR_API_KEY", Version.Standard, false);
Parameters params = new Parameters()
	.addFields("*")
	.addFilter("[themes][not_in]=42")
	.addOrder("published_at:desc");

wrapper.games(params, new onSuccessCallback(){
	@Override
        public void onSuccess(JSONArray result) {
        	// Do something with resulting JSONArray
        }

        @Override
        public void onError(Exception error) {
            	// Do something on error
        }
});
// Kotlin
val wrapper: IGDBWrapper = IGDBWrapper("YOUR_API_KEY")
val params: Parameters = Parameters()
	.addFields("*")
	.addFilter("[themes][not_in]=42")
	.addOrder("published_at:desc")
	
wrapper.games(params, object: OnSuccessCallback{
        override fun onSuccess(JSONArray result) {
        	// Do something with resulting JSONArray
        }

        override fun onError(Exception error) {
            	// Do something on error
        }
})

/* The sent request will look like this:
https://api-2445582011268.apicast.io/games/?search=searchQuery&fields=*&filter[themes][not_in]=42&order=published_at:desc */

Filtering requires extra information in the arguments and needs to be written out like in the example above. Information about Filtering and the postfixes like 'not_in' can be found here.

The rest of the available Endpoints are Available Here. The IGDB API documentation provides details on search parameters.

More examples in java

IGDBWrapper wrapper = new IGDBWrapper("YOUR_API_KEY", Version.Standard, false);

/*
Search for up to two Atari platforms and return their names */
Parameters params = new Parameters()
	.addSearch("Atari")
	.addFields("name")
	.addLimit("2");

wrapper.search(Endpoint.PLATFORMS, params, new OnSuccessCallback(){
	@Override
        public void onSuccess(JSONArray result) {
        	// JSONArray containing 2 Atari platforms
        }

        @Override
        public void onError(Exception error) {
            // Do something on error
        }
});

/* The sent request will look like this:
https://api-2445582011268.apicast.io/platforms/?search=Atari&fields=name&limit=2 */

/*
Search for up to five Zelda games with release dates between 1 Jan and 31 Dec 2011, sorted by release date in descending order.
*/ 

Parameters params = new Parameters()
	.addSearch("Zelda")
	.addFields(“name,release_dates.date,rating,hypes,cover”)
	.addFilter("[release_dates.date][gt]=2010-12-31”)
	.addFilter(“[release_dates.date][lt]=2012-01-01”)
	.addLimit("2")
	.addOffset("0")
	.addOrder(“release_dates.date:desc”);

wrapper.search(Endpoint.PLATFORMS, params, new OnSuccessCallback(){
	@Override
        public void onSuccess(JSONArray result) {
        	// JSONArray containing 5 Zelda games
        }

        @Override
        public void onError(Exception error) {
            // Do something on error
        }
});

/* The sent request will look like this:
https://api-2445582011268.apicast.io/games/?search=Zelda&fields=name,release_dates.date,rating,hypes,cover&filter[release_dates.date][gt]=2010-12-31&filter[release_dates.date][lt]=2012-01-01&limit=5&order=release_dates.date:desc */

/*
Search for two specific games by their IDs
*/

Parameters params = new Parameters()
	.addIds(“18472,18228”)
	.addFields(“name,cover”);

wrapper.games(params, new OnSuccessCallback(){
	@Override
        public void onSuccess(JSONArray result) {
        	// JSONArray containing 2 games
        }

        @Override
        public void onError(Exception error) {
            // Do something on error
        }
});

/* The sent request will look like this:
https://api-2445582011268.apicast.io/games/18472,18228?fields=name,cover 
*/

/*
Search for companies with 'rockstar' in their name. Return up to five results sorted by name in descending order
*/

Parameters params = new Parameters()
	.addSearch("rockstar")
	.addFields(“name,logo”)
	.addFilter(“[name][in]=rockstar”)
	.addLimit("5")
	.addOffset("0")
	.addOrder(“name:desc”);

wrapper.search(Endpoint.COMPANIES, params, new OnSuccessCallback(){
	@Override
        public void onSuccess(JSONArray result) {
        	// JSONArray containing five companies with rockstar in their name
        }

        @Override
        public void onError(Exception error) {
            // Do something on error
        }
});

/* The sent request will look like this:
https://api-2445582011268.apicast.io/companies/?search=rockstar&fields=name,logo&filter[name][in]=rockstar&limit=5&offset=0&order=name:desc */