ISports API Java SDK

A comprehensive Java SDK for the iSports API, providing easy access to football and basketball data.

Features

• Football API: 50+ endpoints covering live scores, schedules, events, lineups, statistics, odds, and more
• Basketball API: 25+ endpoints covering live scores, schedules, lineups, statistics, odds, and more
• Synchronous Client: ISportsClient for blocking operations
• Asynchronous Client: ISportsAsyncClient with CompletableFuture support
• Type-Safe: Generic ApiResponse model with Jackson deserialization
• Error Handling: Comprehensive exception hierarchy (AuthenticationException, RateLimitException, etc.)
• Null-Safe: Optional parameters automatically filtered from requests
• Batch Query Support: matchId and leagueId support comma-separated string values for batch queries
• Open Source: MIT License, Maven-compatible

Requirements

• Java 11+
• Maven 3.6+ or Gradle 7+

Installation

Maven

<dependency>
    <groupId>com.isports</groupId>
    <artifactId>isports-sdk</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'com.isports:isports-sdk:0.1.0'

Quick Start

import com.isports.sdk.ISportsClient;
import com.isports.sdk.model.ApiResponse;

public class Example {
    public static void main(String[] args) {
        ISportsClient client = new ISportsClient("your_api_key");

        // Get today's football livescores
        ApiResponse scores = client.football().liveData().livescoreToday();
        System.out.println(scores.getData());

        // Get football schedule for a specific date
        ApiResponse schedule = client.football().liveData()
            .schedule("2024-01-15", null, null, null, null, null);

        // Get basketball schedule for a specific date
        ApiResponse basketballSchedule = client.basketball().liveData()
            .schedule("2024-01-15", null, null);

        // Search for a football team
        ApiResponse teams = client.football().profile()
            .teamSearch("Manchester United");

        // Batch query multiple football matches by comma-separated matchIds
        ApiResponse matchEvents = client.football().liveData()
            .events("123456789,123456790");
    }
}

Async Usage

import com.isports.sdk.ISportsAsyncClient;
import java.util.concurrent.CompletableFuture;

public class AsyncExample {
    public static void main(String[] args) {
        try (ISportsAsyncClient client = new ISportsAsyncClient("your_api_key")) {
            // Get football and basketball data concurrently
            CompletableFuture.allOf(
                client.football().liveData().livescoreToday()
                    .thenAccept(scores -> System.out.println("Football: " + scores)),
                client.basketball().liveData().livescore()
                    .thenAccept(scores -> System.out.println("Basketball: " + scores))
            ).join();
        }
    }
}

API Coverage

Football

Category	Endpoints	Methods
Live Data	livescore, livescore/today, livescore/change, schedule, schedule/basic, schedule/result, schedule/detail, schedule/change, events, lineup, injury, live_text/match/list, live_text, stats, corner, shooting, match/insights, livegif, animation	20
Profile	league/cup, subleague, cup/stage, team, team/search, player, player/search, referee, stadium, coach, teamlist/player, transfer	12
Stats	standing, cup/standing, standing/subleague, topscorer, analysis, fifa_ranking, playerstats match/list/match, playerstats league/list/league	10
Odds	asia(pre/inplay), 1x2(pre/inplay), ou(pre/inplay), euro(pre/inplay/history), other(pre/inplay), prob(pre/inplay), btts(pre/inplay), ht/ft(pre), corners(pre/inplay), history	22
Common	league/cup/basic, team/player/match modify, country, provider eu/asia/crown/bet365/william/ladbrokes/pinnacle	12

Basketball

Category	Endpoints	Methods
Live Data	livescore, livescore/change, schedule, schedule/detail, lineup, live_text/match/list, live_text, transfer	8
Profile	team, team/search, player, player/search, league/cup, cup/stage, playoffs/stage	7
Stats	standing, cup/standing, stats, quarters/stats, analysis, match/detail, playerstats match/list/match, playerstats league/list	9
Odds	asia(pre/inplay), ou(pre/inplay), euro(pre/inplay/history), other(pre/inplay), inplay	10
Common	league/cup/basic, schedule/basic, match/modify, country, provider eu/asia/crown/bet365/william/ladbrokes/pinnacle	10

Exception Handling

import com.isports.sdk.exception.AuthenticationException;
import com.isports.sdk.exception.RateLimitException;
import com.isports.sdk.exception.ValidationException;

try {
    ApiResponse response = client.football().liveData().livescoreToday();
} catch (AuthenticationException e) {
    // Invalid API key
} catch (RateLimitException e) {
    // Too many requests, retry after a delay
} catch (ValidationException e) {
    // Missing or invalid parameters
}

Parameter Types

Key parameters use String type to support batch queries with comma-separated values:

Parameter	Type	Example
matchId	String	"123456789" or "123456789,123456790" (up to 100 IDs)
leagueId	String	"1639" or "1639,1640"
teamId	String	"12345"
playerId	String	"67890"
cupId	String	"100"

Building from Source

git clone https://github.com/isportsapi/isports-sdk-java.git
cd isports-sdk-java
mvn clean install

Running Tests

mvn test

Project Structure

isports-sdk-java/
├── src/main/java/com/isports/sdk/
│   ├── ISportsClient.java           # Synchronous client entry
│   ├── ISportsAsyncClient.java       # Asynchronous client (CompletableFuture)
│   ├── football/
│   │   ├── FootballApi.java          # Football API factory
│   │   ├── FootballLiveData.java     # Live scores, schedules, events
│   │   ├── FootballProfile.java      # League, team, player info
│   │   ├── FootballStats.java        # Standings, player stats, rankings
│   │   ├── FootballOdds.java         # Pre-match, in-play, historical odds
│   │   └── FootballCommon.java       # Utility endpoints
│   ├── basketball/
│   │   ├── BasketballApi.java        # Basketball API factory
│   │   ├── BasketballLiveData.java   # Live scores, schedules, lineups
│   │   ├── BasketballProfile.java    # Team, player, league info
│   │   ├── BasketballStats.java      # Standings, statistics, quarters
│   │   ├── BasketballOdds.java       # Odds endpoints
│   │   └── BasketballCommon.java     # Utility endpoints
│   ├── http/
│   │   ├── HttpClient.java           # OkHttp synchronous client
│   │   └── AsyncHttpClient.java      # OkHttp async client
│   ├── model/
│   │   └── ApiResponse.java          # Generic response wrapper
│   └── exception/
│       ├── ISportsException.java     # Base exception
│       ├── AuthenticationException.java
│       ├── RateLimitException.java
│       ├── ValidationException.java
│       ├── NotFoundException.java
│       ├── ServerException.java
│       └── NetworkException.java
├── src/test/java/com/isports/sdk/
│   ├── ISportsClientTest.java
│   ├── http/HttpClientErrorTest.java
│   ├── football/FootballLiveDataTest.java
│   ├── football/FootballOddsTest.java
│   └── basketball/BasketballApiTest.java
├── pom.xml
└── README.md

Parameter Filtering

Optional parameters with null values are automatically excluded from API requests:

// Only 'date' is sent; other parameters are filtered out
ApiResponse schedule = client.football().liveData()
    .schedule("2024-01-15", null, null, null, null, null);

Documentation

See the API Documentation for detailed endpoint information.

Links

• Homepage: https://github.com/isportsapiofficial/isports-sdk-java
• Repository: https://github.com/isportsapiofficial/isports-sdk-java
• Issues: https://github.com/isportsapiofficial/isports-sdk-java/issues

License

MIT License