Open source item tracking for all geocaching platforms

  1. Home
  2. GeoKrety XML interface
  1. Read
    1. General
      1. Logtypes
      2. GeoKrety Types
      3. Reference number and id conversion
    2. Database synchronizing
      1. Method 1: export.php All GeoKrety & logs information
      2. Method 2: export_oc.php Only GeoKrety information
    3. Retrieving information
      1. export2.php Retrieve GeoKrety using some filters
  2. Write
    1. secid
    2. logging
    3. responses
    4. Application name/version
    5. Scripts samples
    6. Rate Limits

Read

General

Logtypes

Logtypes are internaly stored using a small integer. The current mapping is as follow:

  • 0 = Dropped to
  • 1 = Grabbed from
  • 2 = A comment
  • 3 = Seen in
  • 4 = Archived
  • 5 = Visiting

Please refer to the help page for more details about each logtype.

GeoKrety Types

GeoKrety Types are internaly stored using a small integer. The current mapping is as follow:

  • 0 = Traditional
  • 1 = A book/CD/DVD…
  • 2 = A human/pet
  • 3 = A coin
  • 4 = KretyPost

Please refer to the help page for more details about each type.

Reference number and id conversion

GeoKrety ids (aka public code) are internaly stored as integer, but this number is generally shown to users as GKXXXX format. This reference number is simply a concatenation of the letters "GK" and the hexadecimal representation of the internal id padded with 0 up to 4 digits.

Convert GKID to integer

<?php
$gk = 'GK1234';
$id = hexdec(substr($gk, 2));
var_dump($id);

# result:
# int(4660)

Convert integer to GKID

<?php
$id = 4660;
$gk = sprintf("GK%04X", $id);
var_dump($gk);

# result:
# string(6) "GK1234"

Database synchronizing

This can be used to synchronize your database with GK database - useful for OpenCaching and other geocaching projects as well as for other purposes 😉

Method 1: export.php All GeoKrety & logs information (slow and large volume of data)

To get list of created GeoKrety after the date and moves registered after the date.

Example: https://geokrety.org/export.php?modifiedsince=20240427114408

Sample output (without headers)

<?xml version="1.0" encoding="UTF-8"?>
<gkxml version="1.0" date="2024-04-27 12:44:08" date_Iso8601="2024-04-27T12:44:08+00:00">
  <geokret id="65536">
    <name><![CDATA[16^4 = 65536 = GK10000]]></name>
    <description><![CDATA[Dies ist der erste fünstellige GeoKret GK10000!
Dieser historische GeoKret wurde mir von kumy, der bei der Entwicklung von GeoKrety hilft, geschenkt.
Er reist nun mit meinem Geocaching-Avatar, dem tschechischen Maulwurf Krtek.
This is the first five digit GeoKret GK10000!
This historix GeoKret was given to me from kumy, who helps developing GoeKrety.
He is not travelling with my Geocaching avatar, the chech mole Krtek.
--
Original description by kumy:
This is the first GeoKret having 5 digits.
Let's celebrate the future!
Why not print and sell really nice "officials" KretyCoins and use the benefits to finance a new hosting server :) ?
You are a designer and want to propose your coin design?
Join us on GitHub: [Link]
You are interested in supporting GeoKrety.org and want to buy a KretyCoin?
Send me a private message [Link] to add you on the pre-order list.]]></description>
    <description_html><![CDATA[<p>Dies ist der erste fünstellige GeoKret GK10000!
Dieser historische GeoKret wurde mir von kumy, der bei der Entwicklung von GeoKrety hilft, geschenkt.
Er reist nun mit meinem Geocaching-Avatar, dem tschechischen Maulwurf Krtek.</p>
<p>This is the first five digit GeoKret GK10000!
This historix GeoKret was given to me from kumy, who helps developing GoeKrety.
He is not travelling with my Geocaching avatar, the chech mole Krtek.</p>
<p>--</p>
<p>Original description by kumy:</p>
<p>This is the first GeoKret having 5 digits.</p>
<p>Let's celebrate the future!</p>
<p>Why not print and sell really nice "officials" KretyCoins and use the benefits to finance a new hosting server :) ?</p>
<p>You are a designer and want to propose your coin design?
Join us on GitHub: [Link]</p>
<p>You are interested in supporting GeoKrety.org and want to buy a KretyCoin?
Send me a private message [Link] to add you on the pre-order list.</p>]]></description_html>
    <description_markdown><![CDATA[Dies ist der erste fünstellige GeoKret GK10000!
Dieser historische GeoKret wurde mir von kumy, der bei der Entwicklung von GeoKrety hilft, geschenkt.
Er reist nun mit meinem Geocaching-Avatar, dem tschechischen Maulwurf Krtek.

This is the first five digit GeoKret GK10000!
This historix GeoKret was given to me from kumy, who helps developing GoeKrety.
He is not travelling with my Geocaching avatar, the chech mole Krtek.

--

Original description by kumy:

This is the first GeoKret having 5 digits.


Let's celebrate the future!

Why not print and sell really nice "officials" KretyCoins and use the benefits to finance a new hosting server :) ?


You are a designer and want to propose your coin design?
Join us on GitHub: [Link]


You are interested in supporting GeoKrety.org and want to buy a KretyCoin?
Send me a private message [Link] to add you on the pre-order list.]]></description_markdown>
    <owner id="17135"><![CDATA[Lineflyer]]></owner>
    <datecreated>2017-09-29 11:46:59</datecreated>
    <datecreated_Iso8601>2017-09-29T11:46:59+00:00</datecreated_Iso8601>
    <distancetravelled>1616</distancetravelled>
    <distancetraveled>1616</distancetraveled>
    <state>3</state>
    <missing>0</missing>
    <position latitude="51.13765" longitude="7.15078"/>
    <waypoints>
      <waypoint><![CDATA[OCHQ10]]></waypoint>
    </waypoints>
    <type id="2"><![CDATA[A human]]></type>
  </geokret>
  <moves id="599227">
    <geokret id="46630"><![CDATA[1. Crailsheimer Volksfest Event]]></geokret>
    <position latitude="49.25772" longitude="9.84128"/>
    <waypoints>
      <waypoint><![CDATA[OC1133F]]></waypoint>
    </waypoints>
    <date moved="2014-09-27 10:00:00" logged="2014-09-27 07:07:16" edited="2017-10-07 22:13:21"/>
    <date_Iso8601 moved="2014-09-27T10:00:00+00:00" logged="2014-09-27T07:07:16+00:00" edited="2017-10-07T22:13:21+00:00"/>
    <user id="26525"><![CDATA[Schnüffelbären]]></user>
    <comment><![CDATA[]]></comment>
    <comment_html><![CDATA[]]></comment_html>
    <comment_markdown><![CDATA[]]></comment_markdown>
    <logtype id="0">drop</logtype>
  </moves>
  <moves id="4662350">
    <geokret id="65508"><![CDATA[16^4 = 65536 = GK10000]]></geokret>
    <position latitude="51.13765" longitude="7.15078"/>
    <waypoints>
      <waypoint><![CDATA[OCHQ10]]></waypoint>
    </waypoints>
    <date moved="2023-08-28 10:00:00" logged="2023-08-28 19:30:18" edited="2023-08-28 19:30:43"/>
    <date_Iso8601 moved="2023-08-28T10:00:00+00:00" logged="2023-08-28T19:30:18+00:00" edited="2023-08-28T19:30:43+00:00"/>
    <user id="12857"><![CDATA[nekromiko]]></user>
    <comment><![CDATA[Auf dem 10. OC-HQ Event gesehen und in ein nettes Gespräch verwickelt ;-)]]></comment>
    <comment_html><![CDATA[<p>Auf dem 10. OC-HQ Event gesehen und in ein nettes Gespräch verwickelt ;-)</p>]]></comment_html>
    <comment_markdown><![CDATA[Auf dem 10. OC-HQ Event gesehen und in ein nettes Gespräch verwickelt ;-)]]></comment_markdown>
    <logtype id="3">met</logtype>
  </moves>
</gkxml>
Method 2: export_oc.php Only GeoKrety information (fast, only most important data; designed for OC sites)

To get list of GK that changed location during last hour.

Example: https://geokrety.org/export_oc.php?modifiedsince=20240427114408

Sample output (without headers)

<?xml version="1.0" encoding="UTF-8"?>
<gkxml version="1.0" date="2024-04-27 12:44:08" date_Iso8601="2024-04-27T12:44:08+00:00">
  <geokret id="46657">
    <name><![CDATA[1. Crailsheimer Volksfest Event]]></name>
    <distancetravelled>0</distancetravelled>
    <state>1</state>
    <position latitude="49.25772" longitude="9.84128"/>
    <waypoints>
      <waypoint><![CDATA[OC1133F]]></waypoint>
    </waypoints>
  </geokret>
  <geokret id="65536">
    <name><![CDATA[16^4 = 65536 = GK10000]]></name>
    <distancetravelled>1616</distancetravelled>
    <state>1</state>
    <position latitude="51.13765" longitude="7.15078"/>
    <waypoints>
      <waypoint><![CDATA[OCHQ10]]></waypoint>
    </waypoints>
  </geokret>
</gkxml>

Retrieving information

export2.php Retrieve GeoKrety using some filters

Sample output (without headers)

<?xml version="1.0" encoding="UTF-8"?>
<gkxml version="1.0" date="2024-04-27 12:44:08" date_Iso8601="2024-04-27T12:44:08+00:00">
  <geokrety>
    <geokret id="46657" type="0" owner_id="26525" ownername="Schnüffelbären" dist="0" date="2014-09-27" lat="49.25772" lon="9.84128" waypoint="OC1133F" state="0" last_pos_id="599227" last_log_id="599227" places="1"><![CDATA[1. Crailsheimer Volksfest Event]]></geokret>
    <geokret id="65536" type="2" owner_id="17135" ownername="Lineflyer" dist="1616" date="2023-08-28" lat="51.13765" lon="7.15078" waypoint="OCHQ10" state="3" last_pos_id="4662350" last_log_id="4662350" places="5" image="GK10000_65039dfc6f7fc"><![CDATA[16^4 = 65536 = GK10000]]></geokret>
  </geokrety>
</gkxml>

  • last_pos_id - id of the last position (waypoint)
  • last_log_id - id of the last log (may be a waypoint, comment etc)

Sample output (with details)

https://geokrety.org/export2.php?gkid=46657&details=1 
<?xml version="1.0" encoding="UTF-8"?>
<gkxml version="1.0" date="2024-04-27 12:44:08" date_Iso8601="2024-04-27T12:44:08+00:00">
  <geokrety>
    <geokret id="65536">
      <name><![CDATA[16^4 = 65536 = GK10000]]></name>
      <description><![CDATA[Dies ist der erste fünstellige GeoKret GK10000!
Dieser historische GeoKret wurde mir von kumy, der bei der Entwicklung von GeoKrety hilft, geschenkt.
Er reist nun mit meinem Geocaching-Avatar, dem tschechischen Maulwurf Krtek.
This is the first five digit GeoKret GK10000!
This historix GeoKret was given to me from kumy, who helps developing GoeKrety.
He is not travelling with my Geocaching avatar, the chech mole Krtek.
--
Original description by kumy:
This is the first GeoKret having 5 digits.
Let's celebrate the future!
Why not print and sell really nice "officials" KretyCoins and use the benefits to finance a new hosting server :) ?
You are a designer and want to propose your coin design?
Join us on GitHub: [Link]
You are interested in supporting GeoKrety.org and want to buy a KretyCoin?
Send me a private message [Link] to add you on the pre-order list.]]></description>
      <owner id="17135"><![CDATA[Lineflyer]]></owner>
      <datecreated><![CDATA[2017-09-29 11:46:59]]></datecreated>
      <datecreated_Iso8601><![CDATA[2017-09-29T11:46:59+00:00]]></datecreated_Iso8601>
      <dateupdated><![CDATA[2024-01-10 21:13:57]]></dateupdated>
      <datecreated_Iso8601><![CDATA[2024-01-10T21:13:57+00:00]]></datecreated_Iso8601>
      <distancetraveled unit="km"><![CDATA[1616]]></distancetraveled>
      <places><![CDATA[5]]></places>
      <state last_pos_id="4662350" last_log_id="4662350"><![CDATA[3]]></state>
      <missing><![CDATA[0]]></missing>
      <position latitude="51.13765" longitude="7.15078"/>
      <waypoints>
        <waypoint><![CDATA[OCHQ10]]></waypoint>
      </waypoints>
      <type id="2"><![CDATA[A human]]></type>
      <image><![CDATA[GK10000_65039dfc6f7fc]]></image>
      <pictures>
        <picture id="52273" type_id="0" type="GeoKret avatar" author_id="17135" author="Lineflyer" url="https://minio.geokrety.org/gk-avatars/GK10000_65039d7328569" thumbnail_url="https://minio.geokrety.org/gk-avatars-thumbnails/GK10000_65039d7328569"/>
        <picture id="52707" type_id="0" type="GeoKret avatar" author_id="17135" author="Lineflyer" url="https://minio.geokrety.org/gk-avatars/GK10000_65039dfc6f7fc" thumbnail_url="https://minio.geokrety.org/gk-avatars-thumbnails/GK10000_65039dfc6f7fc" main="true"/>
      </pictures>
      <moves only_last="10">
        <move>
          <id><![CDATA[1239793]]></id>
          <date moved="2017-10-26 19:47:00" moved_Iso8601="2017-10-26T19:47:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2017.10.23NB0f65"/>
          <comment><![CDATA[Taking this historic Geokret with me for a walk (and some tests with c:geo)! :)]]></comment>
          <logtype id="1"><![CDATA[grab]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1247955]]></id>
          <date moved="2017-11-05 21:16:00" moved_Iso8601="2017-11-05T21:16:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2017.11.01RC2"/>
          <comment><![CDATA[Heute in extra großer Runde und wie immer sehr informativ!  
  
Passend zu einem Thema von heute lasse ich mal den GK10000 hier besuchen, da er gerade in meinem GK-Inventar schlummert.   
  
TFTC!  
#301, 22:16Uhr.  
  
---  
Geloggt mit [c:geo]([link](http://www.cgeo.org)) für Android]]></comment>
          <logtype id="5"><![CDATA[dip]]></logtype>
          <distancetraveled unit="km"><![CDATA[924]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1248198]]></id>
          <date moved="2017-11-06 21:46:44" moved_Iso8601="2017-11-06T21:46:44+00:00"/>
          <user id="26422"><![CDATA[kumy]]></user>
          <application name="www" version="1.x.x"/>
          <comment><![CDATA[Owner change. From: kumy (26422) to: Lineflyer (17135) /GK Team/]]></comment>
          <logtype id="2"><![CDATA[comment]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1254248]]></id>
          <date moved="2017-11-19 11:39:00" moved_Iso8601="2017-11-19T11:39:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2017.11.07RC"/>
          <comment><![CDATA[GKs zum Mitbringen vorübergehend abgelegt   
  
---  
Geloggt mit [c:geo]([link](http://www.cgeo.org)) für Android]]></comment>
          <logtype id="0"><![CDATA[drop]]></logtype>
          <distancetraveled unit="km"><![CDATA[178]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1255818]]></id>
          <date moved="2017-11-21 19:00:00" moved_Iso8601="2017-11-21T19:00:00+00:00"/>
          <user id="38043"><![CDATA[Der Windling]]></user>
          <application name="www" version="1.x.x"/>
          <comment><![CDATA[Beim Bavaria-OC-Stammtisch bin ich heute diesem netten Maulwurf begegnet.  
Beste Grüße vom Windling!]]></comment>
          <logtype id="3"><![CDATA[met]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1256023]]></id>
          <date moved="2017-11-21 18:30:00" moved_Iso8601="2017-11-21T18:30:00+00:00"/>
          <user id="35459"><![CDATA[claralucia9]]></user>
          <application name="www" version="1.x.x"/>
          <comment><![CDATA[Mein erster TB-Geokrety Hybrid...]]></comment>
          <logtype id="3"><![CDATA[met]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1267770]]></id>
          <date moved="2017-12-06 11:00:00" moved_Iso8601="2017-12-06T11:00:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="www" version="1.x.x"/>
          <comment><![CDATA[Du bleibst bei mir]]></comment>
          <logtype id="1"><![CDATA[grab]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1284650]]></id>
          <date moved="2018-01-13 12:12:00" moved_Iso8601="2018-01-13T12:12:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2018.01.02NB2dcd"/>
          <comment><![CDATA[Pling]]></comment>
          <logtype id="0"><![CDATA[drop]]></logtype>
          <distancetraveled unit="km"><![CDATA[488]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1289536]]></id>
          <date moved="2018-01-23 20:22:00" moved_Iso8601="2018-01-23T20:22:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2018.01.15NB9849"/>
          <comment><![CDATA[Du kommst wieder zu mir]]></comment>
          <logtype id="1"><![CDATA[grab]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[1289544]]></id>
          <date moved="2018-01-24 20:20:00" moved_Iso8601="2018-01-24T20:20:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2018.01.15NB9849"/>
          <comment><![CDATA[Geokrets zwischenparken.  
Sie sind hier nur virtuell zwischengelagert und nicht im Cache.  
  
---  
*Geloggt mit [c:geo]([link](http://www.cgeo.org)) für Android*]]></comment>
          <logtype id="0"><![CDATA[drop]]></logtype>
          <distancetraveled unit="km"><![CDATA[1]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[3110425]]></id>
          <date moved="2022-04-03 19:08:00" moved_Iso8601="2022-04-03T19:08:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2022.03.29NBd6dd"/>
          <comment><![CDATA[Testing]]></comment>
          <logtype id="1"><![CDATA[grab]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[3110436]]></id>
          <date moved="2022-04-03 19:09:00" moved_Iso8601="2022-04-03T19:09:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2022.03.29NBd6dd"/>
          <comment><![CDATA[GK-Ablage]]></comment>
          <logtype id="0"><![CDATA[drop]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[3110437]]></id>
          <date moved="2022-04-03 19:10:00" moved_Iso8601="2022-04-03T19:10:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2022.03.29NBd6dd"/>
          <comment><![CDATA[Testing]]></comment>
          <logtype id="1"><![CDATA[grab]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[3110550]]></id>
          <date moved="2022-04-03 19:12:00" moved_Iso8601="2022-04-03T19:12:00+00:00"/>
          <user id="17135"><![CDATA[Lineflyer]]></user>
          <application name="c:geo" version="2022.03.29NBd6dd"/>
          <comment><![CDATA[Test dropping GK]]></comment>
          <logtype id="0"><![CDATA[drop]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[4632631]]></id>
          <date moved="2023-08-26 10:00:00" moved_Iso8601="2023-08-26T10:00:00+00:00"/>
          <user id="20249"><![CDATA[Tungmar]]></user>
          <application name="www" version="1.x.x"/>
          <comment><![CDATA[Es war nett dich kennen zu lernen.]]></comment>
          <logtype id="3"><![CDATA[met]]></logtype>
          <distancetraveled unit="km"><![CDATA[25]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[4634463]]></id>
          <date moved="2023-08-26 11:15:00" moved_Iso8601="2023-08-26T11:15:00+00:00"/>
          <user id="45075"><![CDATA[mrkrid]]></user>
          <application name="www" version="1.x.x"/>
          <comment><![CDATA[Beim HQ-Event beim Owner selbst gesehen]]></comment>
          <logtype id="3"><![CDATA[met]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[4662350]]></id>
          <date moved="2023-08-28 10:00:00" moved_Iso8601="2023-08-28T10:00:00+00:00"/>
          <user id="12857"><![CDATA[nekromiko]]></user>
          <application name="www" version="1.x.x"/>
          <comment><![CDATA[Auf dem 10. OC-HQ Event gesehen und in ein nettes Gespräch verwickelt ;-)]]></comment>
          <logtype id="3"><![CDATA[met]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
        <move>
          <id><![CDATA[4676480]]></id>
          <date moved="2023-08-26 10:10:00" moved_Iso8601="2023-08-26T10:10:00+00:00"/>
          <user id="22735"><![CDATA[fraggulus]]></user>
          <application name="www" version="1.x.x"/>
          <comment><![CDATA[Viele Grüße an den Owner.. :)]]></comment>
          <logtype id="3"><![CDATA[met]]></logtype>
          <distancetraveled unit="km"><![CDATA[0]]></distancetraveled>
        </move>
      </moves>
    </geokret>
  </geokrety>
</gkxml>

General purpose swiches

  • modifiedsince - list of GeoKrety with the timestamp of the last move > modifiedsince (required for some queries) 
    https://geokrety.org/export2.php?modifiedsince=20240427114408
  • lonSW latSW lonNE latNE - list of GeoKrety within the area (restricted to 252000km²) 
    https://geokrety.org/export2.php?lonSW=0&latSW=45&lonNE=6&latNE=50
  • userid - lists GeoKrety owned by userid 
    https://geokrety.org/export2.php?userid=1
  • gkid - lists only one GeoKret 
    https://geokrety.org/export2.php?gkid=141
  • wpt - lists GeoKrety which are in the cache with the specified waypoint
    https://geokrety.org/export2.php?wpt=OP05E5
    It can be used to show GeoKrety in caches with defined waypoint's prefix; eg to show all GeoKrety in romanian caches (prefix GR), just enter:
    https://geokrety.org/export2.php?wpt=GR
  • details - show GeoKrety details, including moves and pictures. (compatible with GeoKretyMap) 
    https://geokrety.org/export2.php?gkid=141&details=1

Above swiches can be mixed. Eg to list my (ownerid=1) GeoKrety which are in GC caches, just enter:

https://geokrety.org/export2.php?userid=1&wpt=GC

Retriving user's inventory

  • userid and inventory=1 - list GeoKrety in user's inventory 
    https://geokrety.org/export2.php?userid=1&inventory=1
  • The same but with secid secret user's identification
    https://geokrety.org/export2.php?secid=xxx&inventory=1
    this request returns also the secret Tracking Codes (the nr variable) for all GeoKrety in user's inventory.

Compressing output

  • adding gzip=1 swich makes output compressed with gzip 
    https://geokrety.org/export2.php?userid=1&inventory=1&gzip=1

Write

secid

Logging of GeoKrety is possible for authenticated users. Authentication require the use of variable secid via POST method. The secid is 128 characters long string, unique for all users (it should be kept secret like a password). The secid can be obtained by passing variables login and password to the script api-login2secid.php via POST method. If correct login credentials are supplied, the secid is returned, else an HTTP 400 code is returned.

Example: $ curl -X POST https://geokrety.org/api-login2secid.php --data "login=someone&password=userpassword" 
26sOchw8re8RE8i7HPTXx50q8aXBUeGhD0QzwPHkmGmyz3fenI6Il1zEfyt9fdmbBBPbisk21xuyLoJQPGFLQDBp3L5IhFjxCFdmc30KyhYeH79GK6O4oDXnst84KYUp
logging

To log a GeoKret, you have to make a POST on https://geokrety.org/ruchy.php script and pass the secid as well as other data you normally pass via form. Anonymous users are not allowed to use the write API.

Base informations

variable
description
secid
authentication string - see above
nr
GeoKret's Tracking Code (ex: GH68MA)
formname
must have value of ruchy
logtype
the move logtype, see help on the top of this document (ex: 0)
data
the log date YYYY-MM-DD (ex: 2012-12-15)
godzina
hour HH (ex: 15)
minuta
minutes MM (ex: 23)
comment
(optional) comment to the log (ex: It is a good place for this GeoKret!)
app
(optional) application name, <=16 chars (ex: c:geo)
app_ver
(optional) application version, <=16 chars (ex: 2019.06.06)
mobile_lang
(optional) error messages language (ex: pl_PL.UTF-8)

Drop or dipped move types

In addition to the basic informations above, some move type require additional values.

variable
description
latlon
latitude and longitude (ex: 52.1534 21.0539)
wpt
the waypoint (ex: OP05E5)
Responses

The actual write API always return it's responses as XML documents.

On success

<?xml version="1.0" encoding="UTF-8"?>
<gkxml version="1.0" date="2024-04-27 12:44:08" date_Iso8601="2024-04-27T12:44:08+00:00">
  <geokrety>
    <geokret id="46657"/>
  </geokrety>
</gkxml>

On error

<?xml version="1.0" encoding="UTF-8"?>
<gkxml version="1.0" date="2024-04-27 12:44:08" date_Iso8601="2024-04-27T12:44:08+00:00">
  <errors>
    <error><![CDATA[Wrong secid]]></error>
    <error><![CDATA[Wrong date or time]]></error>
  </errors>
</gkxml>
Application name/version

If you provide an app name, it would be nice to send us an application icon as svg format (historically we required 16x16, png, eg app icon), so we could display it in log entries along with the app info.

Sample scripts

Scripts samples

Here are sample scripts using GK api

Rate Limits

In order to protect our service from abuse/misbehaving client… We have rate limiting in place.

If you hit a rate limit, we wil respond with the usual http code 429.

A first set of rule limit the request rate per minutes, for any pages.

A second set of rule limit the API calls over a period of time. We're using the Leaky Bucket Algorithm.

The leaky bucket analogy. Water can be added intermittently to the bucket, which leaks out at a constant rate until empty, and will also overflow when full.

The limits are set per IP or per secid depending if the call is authenticated or not.

Your current API usage is available in the headers of each API call. You can also get your current Rate Limit usage using this endpoint: 

<?xml version="1.0" encoding="UTF-8"?>
<gkxml version="1.0" date="2024-04-27 12:44:08" date_Iso8601="2024-04-27T12:44:08+00:00">
  <limits>
    <limit name="API_LEGACY_MOVE_POST" usage-limit="1500" ttl="86400">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_LEGACY_PICTURE_PROXY" usage-limit="5000" ttl="86400">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_V1_CHECK_RATE_LIMIT" usage-limit="250" ttl="86400">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_V1_LOGIN_2_SECID" usage-limit="25" ttl="86400">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_V1_EXPORT2" usage-limit="1500" ttl="86400">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_V1_EXPORT" usage-limit="12" ttl="60">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_V1_EXPORT_OC" usage-limit="12" ttl="60">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_V1_REQUEST_S3_FILE_SIGNATURE" usage-limit="50" ttl="86400">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_GKT_V3_SEARCH" usage-limit="10000" ttl="86400">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="API_GKT_V3_INVENTORY" usage-limit="1500" ttl="86400">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
    <limit name="USERNAME_CHANGE" usage-limit="3" ttl="2419200">
      <usage id="xxx"><![CDATA[0]]></usage>
    </limit>
  </limits>
</gkxml>

Current API rate limits are: