Cgeo: Geocaching.com API

This would of course have to be coordinated with #9...

where is the new api?? I think if there is a API which supports all the features we should use this. ( but only if groundspeak changes the API immediately if they make an update on geocaching.com )

Api is out for selected apps only. Cgeo was one, cgeo opensource is not

I would hope that they do not change the API with every change to the Web-Pages...
Otherwise we could continue to crawl the pages and update our code with every change GC.com implements to their Web pages...
I read that the API will now be available both to premium and basic members with some limitations to basic members.
If you don't mind, I'll get in contact with Ryan at Groundspeak and ask him for API documentation.
Florian.

We have doc, we do not have api access key

I read the notifcation about the upcoming Api some weeks ago. Does anybody have some more pointers?

:( I meant they update the library after changes on gc.com :D

So if you don't mind, I'd ask Groundspeak for an api access key for c-geo (and also clarify with Groundspeak that c-geo-opensource is basically the same as c-geo with just a clarification about the opensource licensing).
Can you send me a copy of the documentation or - if it is on the web somewhere - give me a link to it?
Florian.

Sammy did communicate. Let's wait for him

I contacted them a few weeks ago. The response was one line that told me to send them an application for accessing the API. It seems that there is no public documentation, you need an API-key for the app end every user must get a key over an OAuth-procedure. And they call it "public API"...

I think that we shouldn't hardcode it. It will be easier with the connector-interface so that it makes no difference if we import from spidering, API, OC, gpx, web2cgeo...

Absolutely. I didn't think of the OAuth authentication when I thought of successively switching to the new API.

@SammysHP: Alice in Groundsheep Wonderland:

"When I use a word," Humpty Dumpty said in rather a scornful tone, "it means just what I choose it to mean -- neither more nor less."
"The question is," said Alice, "whether you can make words mean so many different things."
"The question is," said Humpty Dumpty, "which is to be master - - that's all."

Yesterday I got a mail from Groundspeak:

Dear Sven,

Thank you for your patience as we move forward with the Geocaching.com API Program. Attached are two documents for you to review. Please return the completed API Enrollment Form to me and we will send you an API Test Key.

The goal of this public API program is to allow trusted third parties to develop applications and services using the geocaching.com dataset which will primarily serve Groundspeak Premium Members, while also allowing a significant amount of services to be provided for Basic Members. The API will be provided royalty free, so that developers can generate revenue (or not) as they see fit, without having to pay royalties to Groundspeak for data access.

We believe that this will provide you with the ability to best serve the broader community, including new users, while providing additional opportunities for Basic Members to upgrade for full Premium services. Ideally, we would like for members who enjoy the introductory experiences to upgrade to Premium Membership for full application/service access. Specific details regarding this structure are contained within Schedule A to the Agreement. Agreement with the Terms and a completed API Enrollment Form will be required prior to Production database access and formal launch.

Please note that, as a trusted developer, we expect that you will not abuse the API, either in staging or production. Scraping the website for geocaching.com data is not permitted in any application or service for basic or premium members. Rather than allow scraping, we would prefer to develop API calls to suit specific developer needs. If you have any questions regarding potential actions you plan to make with the API, please post them in the API forums and we will do our best to clarify the rules.

A login via Oauth will be required for all users of the API-enabled applications/services. After receiving your completed API Enrollment Form, we will send you a Test Key for you to access the staging server. Then, after reviewing your product and functionality, we will move forward with the Production API Key.

Thank you again. We are very much looking forward to working with you.

Best regards,

Christy

Christy Luther
Business Development Manager
Groundspeak, Inc.
Groundspeak - The Language of Location
www.groundspeak.com
www.geocaching.com

Here is the the API license agreement: http://www.file-upload.net/download-3675937/Groundspeak-API-License-Agreement-17-08-2011.pdf.html

The problem is that the key must be public as every developer compiles his own build (for testing and using). And from what I've heard that's a problem for Groundspeak.
So my suggestion: Wait until the connector-interface is realized and then develop the using of the API as a separate app.

Hi, I shortly skimmed the license agreement. While I do not see an explicit request for confidentiality with respect to the API key that may perhaps be derived from 4.17 or 4.18.
What kills the concept of an external connector is probably 4.16 (derivative work) and 5.3 (end users - not other apps).
Integrating it in c:geo would violate 4.14.
The basic member limits are a joke.
I vote for just ignoring it until they come up with a sensible license model.

I think, it's ok to paste a mail someone got from Bryan:

Hi _________,

We are willing to provide API access to CGeo Opensource. However, since the license key must only be used for the individual application, we are concerned that it might be shared publically. If it is shared publically, it could be used by other applications and that would result in Groundspeak being forced to cancel the specific key. This would, of course, break the application because it would not be able to access data.

So, can you please help me to understand how you plan to limit access to the Authentication key? It cannot be publicly released under any circumstances. Since there are a number of developers working on the Opensource project, we know that it only takes one developer to provide the code externally and then we will all have an issue. Please provide any information that you can and we would be happy to work directly with you, or the main representative for the project, to make this work.

I have included Christy Luther on this email since she is managing the developing process for third party developers.

Thank you!

Sincerely,

Bryan

So they are willing to help us, but also my opinion is to wait until (for better integration, less strict license, maybe an API that doesn't need a key, but only the OAuth key).

what dazzles me: Google is able to manage such development models for their maps api. But groundsheep cannot? Bizarre.

There are two things with Google:

• The Google API checks the certificate, with that the app is signed. The key from Groundspeak should work with every platform and programming language.
• The Google API key is free, so every developer can get one.

I know. It's the groundsheep api process that is causing problems here as different cultures collide: the rigid, apple-like "get off my court" of St Jeremy and the open bazaar-like, where google is strong in. It could have no more contrast. As for the Android-dependent part: if I remember correctly, then you can also use google maps from javascript web apps, so they seem to have a platform-independent method in place. It is the different mindset between google and groundsheep that causes the hickups, google is don't be evil, but what is groundsheep?

AFAIK the key for JavaScript checks the domain.

Take another look, this time at the OSM infrastructure: they need to operate an open environment, yet project their database from misuse. They don't check the apps for editing OSM data: how should this work out at all? With every new release, patch, et cetera ... does St Jeremy want to check every app again? Control neurosis, anyone? So, OSM checks the users. Doesn't seem to be a problem. Maybe I'm missing something, but then why would the OSM model not work for geocaching data?

This were my thoughts when I heard about the new, public API.

The problem with the API key could maybe be solved if every developer gets it's own key - but looking at the limitations for Basic Members I vote against using the api.

BFKC is in contact with Groundspeak, so let us wait. Also the only possibility to implement the API is a connector like the one from GeOrg: http://android.ranitos.de/files/connector-sample.zip I like the way that is used for communication between the app and the connector.

In the meantime you can PM me if you want a link to the API-documentation.

Closing this for the moment, we'll keep this in mind and talk about it again when the connector interface is implemented. See #10

The end user could be responsible to enter a valid user key into c:geo. Dev's can develop each with there own user key.

No, OAuth requires a secret key for the app.

Yes a secret key to generate a user key. Then the user key is used to communicate to the API server. How / where to the user gets there key is up to them.

You say, we should use the account of another app for our purposes?!

What is the Problem if only one Developer gets the key?
There has to be someone who is responsible for releasing the "official" releases into the google store.
So this developer would add the API key into some config file that gets packaged into the apk.
If other developers want to work on the API part of the code, they can apply for API access themselves!
People who want to use custom versions of c:geo would need their own API key obviously, but I think the majority of the users doesn't want to use custom versions. In all cases, this would be better than no API support at all!

The question of the key is only a minor problem. The main issue is, that according to the groundspeak licensing terms you must not get caches into your app by other means then the API.
That would mean we had to build all the functionality around the API, making c:geo effectively a Premium-only App.

Well, a short update regarding this issue.

• Link to the API License Agreement: http://www.geocaching.com/live/api_license_agreement.aspx
• There is a new connector for GeOrg providing gc.com access via the API: https://play.google.com/store/apps/details?id=georg.connector.gcapi
  I'm in contact with the developer and it isn't as easy as it looks like. I cannot say much about it in public.
• There was a plugin for Locus, geocaching4locus: http://geocaching4locus.eu/
  It provided access also for basic members and additionally for premium members (via the API). But now it was blocked by Groundspeak:

Dear Users,

As some of you know, we tried to provide service for basic and premium members with a same limitation. Thus we violated the Geocaching API License Agreement for basic members. Unfortunately, Groundspeak, Inc. (the company that takes care of the Geocaching.com site) detected our actions and we were forced to temporarily suspend distribution of our application on Google Play and other App stores. Some of you was probably experiencing problems with a sign-in in the last few days which may be related with it.

After thinking for a long time we decided to legalize our application, but unfortunately it affects the basic members. Because the basic members are limited to download three full Geocaches per day by this license agreement. This was the reason why we did what we did before. For premium members will be the limit same like before, 6 000 Geocaches per day.

Adapting for a new rules will take several days because of adding confirmation dialogs for the basic members which are required by this license agreement. I hope we will release a new version as soon as possible even at the cost of incomplete translations.

Geocaching4Locus developer team

Assuming that c:geo would be able to get API access from Groundspeak:

1. Which points of the existing API license agreement would need to be discussed and/or modified to match our requirements?
2. Can we keep all existing functions if we change to the API or what technical modifications would be needed for the API to achieve this? I found this help page via Google, but don't know if this reflects the current API.

See also IRC log 18.05.2015

Status:
Letter to Bryan has been send (available for the development team on the Googlegroups mailing list).
Waiting for feedback.

Just for further reference and in case someone is keen to look how that would match into c:geo working mode:
https://api.groundspeak.com/LiveV6/geocaching.svc/help

@Lineflyer I don't trust APIs which have different font sizes in their documentation.

It's not a real documentation I would say, but something autogenerated from code comments.
Clicking the link reveals even more things that make me shudder slightly (Tucson.Geocaching.WCF.API.Geocaching.Types).
That looks like they are not really designing their API as such but use a framework to generate and expose something...

Hello,

This API will be deprecated on the 1st may 2019 but a new REST API is in production since few months now, and the callback URL needs to be authorized by Groundspeak. So, even if the keys are known, no one can't use it because GS will redirect to the callback URL.

(I have the access to this API).

• Developer Documentation - https://api.groundspeak.com/documentation
• Swagger Documentation - https://api.groundspeak.com/api-docs/index

I am afraif, this issue is not up to date. Meanwhile the c:geo core team developers have the possibility to access the latest API (staging environment) and the documentation is available as well.
If you are interested to help we need to clarify what you would need for that and provide appropriate access

I'd like to help you but I'm web developer (php/go), not Android Dev..

To update this issue: We are in contact with Groundspeak for a long time, evaluating how we can use the API. There are still some open (non-technical) issues to solve, but we already received development keys for the new API. As the next step we have to design the integration into c:geo (for example if it is just a new connector or if other changes are necessary). For that and the following implementation phase any help is appreciated.

Some terms of use of the Groundspeak API were problematic in the past (impossible or hard to get keys for development purpose for anybody asking, drastic daily limitations in the number of caches retrieved and their D/T ratings for basic members, impossible to show caches from concurrent websites like opencaching…), were these issues resolved or are they these nontechnical remaining issues you mention?
I don't see Groundspeak changing their mind about their business model and their (lack of) openness, seeing their current API restrictions.

Well, Groundspeak showed some willingness to discuss this non-technical issues and we already gave some proposals. However to further discuss this, we probably need to see the impact/difference between API usage and current implementation in the usage flow.

I would rather not like to provide any details in this open forum, however we will for sure take aynone willing to work on the API implementation into this discussion as well as involving our users before a final decision.

Anything new here? I dabbled with the API before and it's not too bad to implement. Also looked at the new version they have now.
Question is: is anyone leading this topic?
I feel like it could be a great boost for c:geo to get this done.
What's the technical hold up?

What's the technical hold up?

Basically manpower.

But there are still some open issues regarding terms of use. So it is highly possible that a technical implementation won't be used in the current form or at all if there is no agreement with Groundspeak.

I think we should start with some sort of abstract requirements analysis, then proceed with a list of affected areas in c:geo and necessary changes.

There is no technical hold-up. Whether the Api is able to bear all the functionality we now have has to be checked in detail though.
From my personal side, there is a lack of resources and a lack of an acceptable agreement regarding Api usage for basic members.
BTW: Where do you see the boost for c:geo as such in this topic? It would be a bit 'cheaper' development-resource wise and it would be cheaper for groundspeak to serve the c:geo users, but otherwise? I don't see any big advantages in c:geo using the Api for the 'average Joe'. The power-users certainly have other workflows involving GSAK and mobile tools that plug in to that chain.