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, CENTRAL_SNAPSHOTS);

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

Gradle, Maven, etc...

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

repositories {
    mavenCentral()
    maven { url = uri("https://central.sonatype.com/repository/maven-snapshots/") } // only needed for SNAPSHOT
}

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

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 ShortenConfig.Builder("https://www.example.com/")
        .shorturl("foobar")
        .callback("test")
        .logstats(true)
        .format(Format.JSON)
        .build();

Isgd.shorten(config);

var config = new LookupConfig.Builder("https://is.gd/Pt2sET")
        .callback("test")
        .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

See CONTIBUTING.md for information about contributing to this project.