instagram4j

📷 Java wrapper using OkHttpClient for Instagram's private api (Android emulation)

Table of contents

• Install
• Overview
  • Features
• Usage
  • Terms and Conditions
  • Quick Usage
  • Setup & Login
    • Simple Login
    • Two factor login
    • Challenge login
    • Login with proxy
  • Sending requests and actions
  • Serialization
• Contributing

Install

The latest stable release:

Example for gradle:

dependencies {
    implementation 'com.github.instagram4j:instagram4j:2.0.3'
}

Example for maven:

  <dependencies>
    <dependency> 
      <groupId>com.github.instagram4j</groupId>
      <artifactId>instagram4j</artifactId>
      <version>2.0.3</version>
    </dependency> 
  </dependencies>

For develop (unreleased to central) builds, jitpack can be used.

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

dependencies {
    implementation 'com.github.instagram4j:instagram4j:master-SNAPSHOT'
}

Example for maven:

  ...
  <dependencies>
      ...
    <dependency> 
      <groupId>com.github.instagram4j</groupId>
      <artifactId>instagram4j</artifactId>
      <version>master-SNAPSHOT</version>
    </dependency> 
  </dependencies>
  ...
  <repositories>
    ...
    <repository>
      <id>jitpack</id>
      <url>https://jitpack.io</url>   
    </repository>
 </repositories>

Requirements

This project depends on

• Java 8+
• okhttpclient
• okhttpclient url connection
• jackson data-bind
• jackson annotations
• slf4j-api
• apache commons codec

Overview

This Java library provides requests that emulate the Android Instagram app. Most of the official app functionality is supported here. This library has undergone a massive rewrite (instagram4j 1.x.x is not compatible) The rewrite intends to help with maintainability and flexibility throughout time.

Features

Most of the Android Instagram app features are supported. Here are some notable ones.

• OkHttpClient and jackson-databind
• two factor login
• support for challenges
• iterable feeds
• serialization
• timeline, story, live, direct messaging, shopping, and more!

Usage

Terms and Conditions

This library is intended for personal use and for educational experiences due to limitations of Instagram's public API.

• Please use Instagram's public API if possible
• Do not use this library to spam (botting, spam messaging, etc...)
• There will be no support for those with malicious intent
• Use reasonable (human) delay in between sending requests
• Don't be evil.

This library is in no way affiliated with, authorized, maintained, sponsored or endorsed by Instagram or any of its affiliates or subsidiaries. This is an independent and unofficial API. Use at your own risk.

Contributors are not responsible for usage and maintainability. Due to the nature of this project, some features of the library are not guaranteed as they make change and break in the future. This library is licensed under ASL.

Quick Usage

Login:

IGClient client = IGClient.builder()
        .username("username")
        .password("password")
        .login();

Actions:

IGClient client = ...

client.actions()
.timeline()
.uploadPhoto(new File("myPhoto.jpg"), "My Caption")
.thenAccept(response -> {
    System.out.println("Successfully uploaded photo!");
})
.join(); // block current thread until complete

Executing requests:

IGClient client = ...

// Alternatively use client.sendRequest
new FeedTimelineRequest().execute(client)
.thenAccept(response -> {
    response.getFeed_items().forEach(...);
})
.join(); // block current thread until complete

Setup and Login

An IGClient instance must be constructed and logged in to send most requests.

Simple Login

Basic login using IGClient builder method.

Example:

IGClient client = IGClient.builder()
        .username("username")
        .password("password")
        .login();

Example:

// simulate pre login flow (synchronous) and post login flow (asynchronous)
IGClient client = IGClient.builder()
        .username("username")
        .password("password")
        .simulatedLogin();

Two factor login

Provide a consumer that may resolve two factor login process. The example uses the included utility to resolve two factor logins.

Example:

Scanner scanner = new Scanner(System.in);

// Callable that returns inputted code from System.in
Callable<String> inputCode = () -> {
    System.out.print("Please input code: ");
    return scanner.nextLine();
};

// handler for two factor login
LoginHandler twoFactorHandler = (client, response) -> {
    // included utility to resolve two factor
    // may specify retries. default is 3
    return IGChallengeUtils.resolveTwoFactor(client, response, inputCode);
};

IGClient client = IGClient.builder()
        .username("username")
        .password("password")
        .onTwoFactor(twoFactorHandler)
        .login();

Challenge login

Sometimes a challenge may arise when logging in. Provide a LoginHandler to handle challenges. The example uses the included utility to handle challenges automatically.

Example:

Scanner scanner = new Scanner(System.in);

// Callable that returns inputted code from System.in
Callable<String> inputCode = () -> {
    System.out.print("Please input code: ");
    return scanner.nextLine();
};

// handler for challenge login
LoginHandler challengeHandler = (client, response) -> {
    // included utility to resolve challenges
    // may specify retries. default is 3
    return IGChallengeUtils.resolve(client, response, inputCode);
};

IGClient client = IGClient.builder()
        .username("username")
        .password("password")
        .onChallenge(challengeHandler)
        .login();

Login with proxy

You may provide Proxy and Authenticator for the Proxy thru configuring an OkHttpClient and passing it in thru the builder.

OkHttpClient httpClient = new OkHttpClient.Builder().proxy(...).build();
IGClient client = IGClient.builder()
        .username("username")
        .password("password")
        .client(httpClient)
        .login();

Sending requests and actions

This library provides a limited wrapper api that may be used to locate and send common requests. Not all features are supported through actions currently. Actual requests are located under the requests package and can be sent through IGClient like in previous versions. Requests can be sent asynchronously. All requests return a CompletableFuture.

Simple Example:

IGClient client = ...

client.actions().timelime()
.uploadPhoto(new File("myPhoto.jpg"), "My Caption")
.thenAccept(res -> {
    // perform actions with response
    log.info("Uploaded photo {}", response.getMedia().getId());
})
.exceptionally(tr -> {
    // something has terribly gone wrong!
    // handle exception
    
    return null;
})
.join(); // blocks currect thread until completion

Chainng Example:

IGClient client = ...

// finds user by username then gets friendship status
client.actions().users()
.findByUsername("instagram")
.thenCompose(UserAction::getFriendship)
.thenAccept(friendship -> {
    // response here
})
.join();

// uploads a photo then comments on it
client.actions().timeline()
.uploadPhoto(new File("myPhoto.jpg"), "My Caption")
.thenCompose(response -> {
    // action with response
    return new MediaCommentRequest(response.getMedia().getId(), "First comment!").execute(client)
})
.join();

Serialization

IGClient is a Serializable object that can be saved and later reconstructed. Session cookies however must be separately serialized. Session cookies for OkHttpClient are done through an implementation of CookieJar. You may provide your own implementation of a serializable cookie jar and then serialize your cookies for later use. Session cookies are good for 90 days and avoids relogins.

See example for serialization and deserialization here.

Contributing

See Issues tab to find good starting issues to work on. If you have an addition you would like to make, please do not hesitate to make a pull request!