https://github.com/ethauvin/isgd-shorten
is.gd Shortner for Kotlin, Java & Android
https://github.com/ethauvin/isgd-shorten
android isgd java kotlin library shorten shorten-links shorten-urls shortener shortener-service shorturl url-shortener vgd
Last synced: 10 months ago
JSON representation
is.gd Shortner for Kotlin, Java & Android
- Host: GitHub
- URL: https://github.com/ethauvin/isgd-shorten
- Owner: ethauvin
- License: bsd-3-clause
- Created: 2020-03-22T02:23:01.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-07-11T18:44:26.000Z (12 months ago)
- Last Synced: 2025-07-26T11:35:33.080Z (11 months ago)
- Topics: android, isgd, java, kotlin, library, shorten, shorten-links, shorten-urls, shortener, shortener-service, shorturl, url-shortener, vgd
- Language: Kotlin
- Homepage:
- Size: 678 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://kotlinlang.org/)
[](https://rife2.com/bld)
[](https://github.com/ethauvin/isgd-shorten/releases/latest)
[](https://central.sonatype.com/artifact/net.thauvin.erik/isgd-shorten)
[](https://github.com/ethauvin/isgd-shorten/packages/2260776/versions)
[](https://sonarcloud.io/dashboard?id=ethauvin_isgd-shorten)
[](https://github.com/ethauvin/isgd-shorten/actions/workflows/bld.yml)
[](https://circleci.com/gh/ethauvin/isgd-shorten/tree/master)
# [is.gd](https://is.gd/developers.php) Shortener for Kotlin, Java & Android
A simple implementation of the [is.gd](https://is.gd/) URL shortening and lookup [APIs](https://is.gd/developers.php).
## Examples (TL;DR)
```kotlin
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](https://github.com/ethauvin/isgd-shorten/blob/master/examples/bld) or [Gradle](https://github.com/ethauvin/isgd-shorten/blob/master/examples/gradle) Examples.
## JSON or XML
The [is.gd API](https://is.gd/developers.php) can return data in plain text (default), JSON or XML.
```kotlin
Isgd.shorten("https://www.example.com/", format = Format.JSON)
```
returns:
```json
{ "shorturl": "https://is.gd/Pt2sET" }
```
## Parameters
All of the [is.gd API](https://is.gd/developers.php) parameters are supported:
```kotlin
Isgd.shorten(
url = url,
shorturl="foobar",
callback = "test",
logstats = true,
format = Format.JSON)
```
returns:
```js
test({ "shorturl": "https://is.gd/foobar" });
```
## bld
To use with [bld](https://rife2.com/bld), include the following dependency in your [build](https://github.com/ethauvin/isgd-shorten/blob/master/examples/bld/src/bld/java/com/example/ExampleBuild.java) file:
```java
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](https://gradle.org/), include the following dependency in your [build](https://github.com/ethauvin/isgd-shorten/blob/master/examples/gradle/build.gradle.kts) file:
```gradle
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](https://central.sonatype.com/artifact/net.thauvin.erik/isgd-shorten).
## Java
To make it easier to use the library with Java, configuration builders are available:
```java
var config = new ShortenConfig.Builder("https://www.example.com/")
.shorturl("foobar")
.callback("test")
.logstats(true)
.format(Format.JSON)
.build();
Isgd.shorten(config);
```
```java
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:
```kotlin
try {
Isgd.shorten("https://is.gd/Pt2sET") // already shorten
} catch (e: IsgdException)
println("Status Code: ${e.statusCode}")
println("${e.message})
}
```
```console
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](https://v.gd/) by setting the `isVgd` flag:
```kotlin
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:
```console
git clone git@github.com:ethauvin/isgd-shorten.git
```
Then use [bld](https://rife2.com/bld) to build:
```console
cd isgd-shorten
./bld compile
```
The project has an [IntelliJ IDEA](https://www.jetbrains.com/idea/) project structure. You can just open it after all the dependencies were downloaded and peruse the code.