gcUnicorn

gcUnicorn is an opensource tool for geocaching.com platform. You can use it either as a web application requiring nothing more but Java JRE installed on your machine or as an Android application.

The tool allows you to search for caches of selected types within given coordinates and radius. Its output contains not only exhaustive cache details, but links to spoiler images, detailed log entries including links to uploaded pictures as well. The output is served as GPX file with following schemas applied to it:

• GPX v1.1
• Groundspeak v1.0.1
• Gsak v1.6

GPX file created by the application is readable by following applications:

• Cachly
• Locus

If you test the output GPX format with other applications, please, let me know, so I can update the list. Thank you.

Disclaimer

Be sure to read Groundspeak's terms of use. By using the application you may violate some of them and your Geocaching account may be suspended or deleted.

Author of the application is not responsible for any damage caused by using it.

Modules

The application contains two modules:

• core - Core functionality.
• webapp - Web application. UI has been created with simplicity and perfect readability in mind so it works on your desktop and mobile devices with no issues.
• android - Android application. It allows you to the the very same operations like webapp module.

Screenshots

Web application

See gcUnicorn-webapp album for full resolution screenshots.

Android application

See gcUnicorn-android album for full resolution screenshots.

How to run

Web application

For Windows OS there is an executable file created. This approach always enables tray icon.

If you want to run the application from within command line, run the following command:

java -jar gcUnicorn-webapp-<version>.jar

The application is then available at http://<hostname>:8080/. Most likely it will be http://localhost:8080/

Login page

On the login page you have to provide your Geocaching credentials. The credentials are not being stored anywhere nor send to any 3rd party servers. The application uses them to log you into Geocaching page.

Search page

Coordinates field supports following standards:

• Decimal degrees format with following examples:

  • N 18,556°, E 45.555°

  • N18,W 45.555

  • N 18,556 , E 45°

  • 18,556N , 45°E

  • s 18.556° , W45°

  • 18.556° s, 45° w

• Degrees decimal minutes format with following examples:

  • N 18° 55', E 45° 55'

  • N9° 55', E 45° 55

  • N 18,556 , E 45°

  • N 18°, E 45° 55'

  • S°55.55',W45°

Queue page

Here you can see all your search jobs. If a job is still running, spinning circle is shown. Once the job is done, download icon is shown.

How to configure

The application uses Spring Boot so basic configuration can be done by creating application.properties file next to the gcUnicorn-webapp-<version>.jar with properties specified inside it.

The list of all available properties (not all of them are applicable to the application) can be found on Spring Boot reference page.

If the application will be exposed on the internet it is recommended to enable SSL within the application. You can do that by specifying required server.ssl.* properties and providing valid certificate. See the reference page for more details.

You can find examples of configuration files inside webapp module.

Application port

You have two options how to configure application port:

• Add -Dserver.port=<port-number> argument to the executing command:

java -jar -Dserver.port=<port-number> gcUnicorn-webapp-<version>.jar

• Create/edit application.properties file next to the gcUnicorn-webapp-<version>.jar with following content:

server.port=<port-number>

Logging configuration

The application uses Logback implementation. You can read about its configuration on its homepage.

You can specify logging configuration with following options:

• Add -Dlogging.config=file:<path-to-logging-config> argument to the executing command:

java -jar -Dlogging.config=file:<path-to-logging-config> gcUnicorn-webapp-<version>.jar

• Create/edit application.properties file next to the gcUnicorn-webapp-<version>.jar with following content:

logging.config=file:<path-to-logging-config>

Displaying tray icon

If you want to shut down the application quickly, tray icon can be handy. To display the tray icon, you have two options here as well:

• Add -Dtray argument to the executing command:

java -jar -Dtray gcUnicorn-webapp-<version>.jar

• Create/edit application.properties file next to the gcUnicorn-webapp-<version>.jar with following content:

tray

Android application

To install the application, you have to enable Unknown Sources first.

Android version of the tool supports all Android version since Lollipop (API 21) onwards.

As a bonus, the application interacts with popular Android map application called Locus Map. You can find shortcuts to gcUnicorn within main Geocaching functions menu and within Point view's share option. If you open the application from later option, latitude and longitude will be transferred from Locus directly into the gcUnicorn.

Up until Android Lollipop (API 21), all the created GPX files are stored within <externalStorage>/gcUnicorn/gpx. Starting from API 21, all the GPX files are stored within external application folder <externalStorage>/Android/data/cz.babi.gcunicorn.android/files/gcUnicorn/gpx.

How to build

Clone the repository:

git clone https://github.com/little-fish/gcUnicorn.git

Navigate to the cloned folder:

cd gcUnicorn

Build the applications:

./gradlew build

Created artifacts for core and webapp modules are located within <module>/build/libs folder. For android module the artifact is located within <module>/build/outputs/apk.

android

To enable location picking from Google Maps, Google Places API key has to be provided during build time.

To obtain your key, follow the instruction: Get API Key and Project setup. The application doesn't use Places API.

Once you obtain your key, you have to specify it within root project's local.properties file. Otherwise, location picking won't work properly.

Signing

core & webapp

Core and webapp modules could use two different signing mechanisms. It is up to you which one you choose.

• Gradle Signing plugin - You can read about it on its homepage.
• jarsigner - Read more here.

If you want to use any of the methods mentioned above, you have to create keystore.properties file within module directory and specify additional (self-explanatory) properties:

• Gradle Signing plugin:

  • signing.keyId
  • signing.password
  • signing.secretKeyRingFile

  Once all the properties are provided, all output artifacts will be signed automatically.

• jarsigner:

  • jarsigning.keystore
  • jarsigning.keystoreType
  • jarsigning.keystorePassword
  • jarsigning.keyPassword
  • jarsigning.alias

  Once all the properties are provided, signedJar (signedBoorJar respectively) Gradle task will be created and hooked into the build process.

android

Android module uses standard signing described on Android publishing page. To enable signing, simply create keystore.properties within the module directory and specify additional (self-explanatory) properties:

• keyAlias
• keyPassword
• storeFile
• storePassword

Once the properties are provided, signing will be enabled automatically.

Additional notes

• Skip premium caches - If enabled the tool will simply skip premium caches earlier. If you are a basic member and disable this option, the tool will try to load cache's details anyway and once it discovers that it can not load the cache (because you are a basic member), it skips it. (The tool has no idea whether you are a basic member or a premium one.)

Release notes

2023-06-03: core v3.0.0 webapp v1.1.0 & android v1.1.0

• Updated to the latest Gradle with all the related improvements (configuration and build caches, version library, ...)

• Updated all the dependencies to the latest versions available.

• core

  • Used different method for cache searching.

• android

  • Minimal Android version required is Android 5.0 (SDK 21).

• webapp

  • Spring Boot 3 is used.

2022-03-14: core v2.0.5 & webapp v1.0.8 & android v1.0.6

• core
  • Fixed parsing of some attributes.
• android
  • Added support for Android 13.

2021-06-19: core v2.0.4 & webapp v1.0.7 & android v1.0.5

• core
  • Updated regular expressions.

2020-02-13: core v2.0.3 & webapp v1.0.6 & android v1.0.4

• core
  • Updated parsers.
• webapp
  • Updated value of Content-Type header.

2020-02-08: core v2.0.2 & webapp v1.0.5 & android v1.0.3

• core
  • Removing invalid XML characters from output GPX file.
• Updated dependencies.

2019-03-25: core v2.0.1

• core
  • Cache's long description is loaded successfully.

2018-11-24: android v1.0.1

• android
  • Changed navigation between activities.

2018-11-23: core v2.0.0 & webapp v1.0.3 & android v1.0.0

• core
  • Removed Java 8 features not available at Android SDK 16. (See How to build.)
  • Updated exception handling.
• webapp
  • Changed default cache count from 50 to 100.
• android
  • First release.
• Added signing options to all modules.
• Updated dependencies to newer versions.

How to contribute

Any kind of contribution is welcome. If you have any ideas, bug-fxies or improvements, just create a pull request or contact me via email. Thank you.

How to donate

Acknowledgment

Special thanks to c:geo team for inspiring me to create the application.

Roadmap

• A manager for already created GPX files. ETA depends on users requests..