is.gd Shortener for Kotlin, Java & Android

A simple implementation of the is.gd URL shortening and lookup APIs.

Examples (TL;DR)

import net.thauvin.erik.isgd.Isgd

...

Isgd.shorten("https://www.example.com/") // returns https://is.gd/Pt2sET
Isgd.lookup("https://is.gd/Pt2sET") // returns https://www.example.com

• View bld or Gradle Examples.

JSON or XML

The is.gd API can return data in plain text (default), JSON or XML.

Isgd.shorten("https://www.example.com/", format = Format.JSON)

returns:

{ "shorturl": "https://is.gd/Pt2sET" }

Parameters

All of the is.gd API parameters are supported:

Isgd.shorten(
    url = url,
    shorturl="foobar",
    callback = "test",
    logstats = true,
    format = Format.JSON)

returns:

test({ "shorturl": "https://is.gd/foobar" });

bld

To use with bld, include the following dependency in your build file:

repositories = List.of(MAVEN_CENTRAL, SONATYPE_SNAPSHOTS_LEGACY);

scope(compile)
    .include("net.thauvin.erik:isgd-shorten:1.0.`");

Gradle

To use with Gradle, include the following dependency in your build file:

repositories {
    mavenCentral()
    maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots") } // only needed for SNAPSHOT
}

dependencies {
    implementation("net.thauvin.erik:isgd-shorten:1.0.1")
}

Instructions for using with Maven, Ivy, etc. can be found on Maven Central.

Java

To make it easier to use the library with Java, configuration builders are available:

var config = new Config.Builder()
        .url("https://www.example.com/")
        .shortUrl("foobar")
        .callback("test")
        .logStats(true)
        .format(Format.JSON)
        .build();

Isgd.shorten(config);

var config = new Config.Builder()
        .shortUrl("https://is.gd/Pt2sET")
        .format(Format.XML)
        .build();

Isgd.lookup(config);

Errors

An IsgdException is thrown when an API error occurs. The error message (text, XML or JSON) and HTTP status code can be retrieved as follows:

try {
    Isgd.shorten("https://is.gd/Pt2sET") // already shorten
} catch (e: IsgdException)
    println("Status Code: ${e.statusCode}")
    println("${e.message})
}

Status Code: 400
Error: Sorry, the URL you entered is on our internal blacklist. It may have been used abusively in the past, or it may link to another URL redirection service.

v.gd

Additionally, link can be shortened using v.gd by setting the isVgd flag:

Isgd.shorten("https://www.example.com/", isVgd = true) // returns https://v.gd/2z2ncj

Contributing

If you want to contribute to this project, all you have to do is clone the GitHub repository:

git clone git@github.com:ethauvin/isgd-shorten.git

Then use bld to build:

cd isgd-shorten
./bld compile

The project has an IntelliJ IDEA project structure. You can just open it after all the dependencies were downloaded and peruse the code.