ver. 1958 (4e4db56)
Introduction
Sign up
Examples
Changelog
services/apiref
issue
method
method_index
services/apisrv
installation
installations
stats
services/attrs
attribute
attribute_index
attributes
services/caches
edit
geocache
geocaches
mark
save_personal_notes
services/caches/formatters
garmin
ggz
gpx
services/caches/map
tile
services/caches/search
all
bbox
by_urls
nearest
save
services/caches/shortcuts
search_and_retrieve
services/logs
capabilities
delete
edit
entries
entry
logs
submit
userlogs
services/logs/images
add
delete
edit
services/oauth
access_token
authorize
request_token
services/replicate
changelog
fulldump
info
services/users
by_internal_id
by_internal_ids
by_username
by_usernames
user
users

Get the list of changes for your database
:: services/replicate/changelog method

Minimum Authentication: Level 1 (see Authentication Levels)
https://www.opencaching.us/okapi/services/replicate/changelog

Get the list of changes to be replayed on your own copy of Opencaching database. Use this method periodically (e.g. every 5 minutes) to keep your database in sync with ours.

For some applications it might be desireable to have a quick access to the entire Opencaching database (instead of querying for specific portions of it). You may use OKAPI's replicate module to achive this effect. The changelog method is the primary replication service which you will use. However, to correctly set up your first database copy, you will need to use the fulldump method.

A couple of things for you to remember:

  • You must update your database frequently for this method to work. We don't keep the changelog indefinitelly. You must update at least once a week!
  • You should not update your database more frequently than once per 5 minutes. This could kill our servers, and it wouldn't do you any good, since we update the changelog only once every 5 minutes anyway.

Let's assume that you already have a copy of OKAPI database, but it's already 2 days old. You want to use the changelog method to update your copy to the most current state.

Changelog is the list of all changes which appeared in the OKAPI database since the last time you downloaded it. What you have to do is to download this list of changes and to replay them on your copy of our database. After you do this, your database is up-to-date.

We use revision numbers to keep track of all the versions of the database. Every time we update a database, the revision is increased. You will also receive this number every time you fetch a changelog or a fulldump of our database. You must keep this number carefully, because you need it in order for us to generate a proper changelog for you next time you ask for it!

Example. This is a valid list of requests you should issue and their responses:

  • fulldump - you receive a fulldump of our database with the revision number 238004. You will call this method only once (to initiate your copy of the database).
  • changelog?since=238004 - OKAPI checks if there were any changes recorded since revision 238004. It responds with the list of changes and the new revision number 238017. You replay the changes on your database.
  • You wait for some time between requesting the changelog again.
  • Upon your next update, you'll ask for changelog?since=238017, etc.
since required

Current revision of your database. This should be the same as the value of revision attribute, which you received with your previous update.

Old revisions are deleted, the since argument MUST referer to a revision no older than 10 days. You will have to download a fulldump if you have an older copy (shame on you!).
format optional Standard common formatting argument.
callback optional Standard common formatting argument.
Plus required consumer_key argument, assigned for your application.

Returned value:

A dictionary of the following structure:

  • changelog - a list of dictionaries. Each dictionary has the following structure:

    • object_type - string, object type to which the change refers to. One of the following values:

      • geocache - this change refers to a geocache object,
      • log_entry - this change refers to a log entry.

      More object types will come in the future. You should ignore all changelog entries with an unknown object_type.

    • object_key - a dictionary of fields which compose the primary key for the object. This will be the code field for the geocache object, and uuid field for the log_entry object.

    • change_type - string, the type of the change. One of the following values:

      • replace - the object was inserted or updated. You should check if you already have the object in your database. If you have it, you should update its fields accordingly. If you don't, you should create it.
      • delete - the object was deleted. You should check if you already have the object in your database. If you do, you should delete it.

    • data - a dictionary of fields associated with the object (present only if change_type equals replace).

      • For geocache objects, this might be any subset of fields described in the services/caches/geocache method. Note that not all of these fields will be included here (i.e. latest_logs will not).
      • For log_entry objects, this might be any subset of fields described in the services/logs/logs method, plus additional cache_code field, the code of the geocache to which the log entry refers to.

      In theory this dictionary should contain only these fields which actually changed. In truth, it MAY contain all the other fields too. This behavior may change in future.

    You should iterate through this changelog sequentially. All the changes should be applied in the same order as they were listed in the changelog. Single object may appear multiple times inside the changelog. Changelog will contain all the changes which occured since the time you specified in the since parameter and it MAY contain some more, which were submitted before this date (see below). The changes which are unnecessary MAY be skipped (ex. when cache description changes multiple times, we may want to include only the last change).

  • revision - this is the revision number which you should use in the since parameter when you call this method next time.

  • more - boolean. If false, then it means that the entire changelog had been pulled. If true, then there are more items waiting to be pulled - you should rerun this method again (with the value of revision inserted in the since parameter).

    The changelog is usually tiny, but it also might be huge at times. It may even contain all the caches in the database (i.e. if we decide to do some changes on all caches in a bulk). This is the reason why we introduced the more attribute. It makes it easier to parse the changelog sequentially.

The response MAY contain changes recorded before the revision which you stated in your since parameter. This is due to caching. If we already have a response ready, that was produced for a "since" parameter which was a little more in the past, we may want to return this cached copy, instead of producing a new one. It will be faster for us, and you shouldn't even notice. We will still make sure to set the revision and more attributes in a correct way, which in turn will make you query us again, if you need to.