Geocaching Australia API: Search for Nearest Geocaches
Retrieve a list of nearest geocaches
Geocaching Australia API call: https://geocaching.com.au/api/services/search/nearest/
Parameters not explicitly detailed will be silently ignored if passed.
Geocaches are returned in increasing distance from the center point. If the limit is exhausted prior to the full list of geocaches being returned, they will appear to be centered around the center point.
Calling the method
Field | Definition | Description |
consumer_key | Mandatory | The api key associated with your app. |
center | Mandatory | A latitude and longitude separated by |. e.g. -37|145 |
type | Optional | A valid cache type. Use https://geocaching.com.au/api/services/enum/cachetype for a comprehensive list. Caches that match any of these values will be returned. A leading - will EXCLUDE these cache types from the search. |
status | Optional | A cache status or Available, Temporarily unavailable or Archived. Caches that match any of these values will be returned. |
radius | Optional | A distance from the provided latitude and longitude in kilometers (decimals are permitted). |
terrain | Optional | A string 'X-Y' (example 2-3.5), where X and Y are decimals between 1 and 5, are both divisible by 0.5 and X <= Y. Only caches with terrain rating between these numbers (inclusive) will be returned. |
difficulty | Optional | A string 'X-Y' (example 2-3.5), where X and Y are decimals between 1 and 5, are both divisible by 0.5 and X <= Y. Only caches with terrain rating between these numbers (inclusive) will be returned. |
size2 | Optional | A valid cache size. Use https://geocaching.com.au/api/services/enum/cachesize for a comprehensive list. Caches that match any of these values will be returned. A leading - will EXCLUDE these cache types from the search. |
found_status | Optional | Identifies whether to return caches that have been found by the user, not found by the user or all. Valid values are found_only to return only found caches, notfound_only to return only caches that have not been found or any other value (or blank) to return all caches regardless of find status. |
watched_only | Optional | Identifies whether to return caches from the user watchlist. Valid values are true to return only caches on the user watchlist. Any other value will ignore the watchlist. |
exclude_my_own | Optional | Identifies whether to return caches that are owned by the user. Valid values are true to return caches that are not owned by the user. Any other value wil return all caches regardless of whether they are owned by the user. |
ftf_hunter | Optional | Identifies whether to return caches that have not been found. Valid values are true to return caches that have not yet been found. Any other value wil return all caches regardless of whether they are found or not. |
limit | Optional | Number of caches to be returned. Default is 100. Valid values are integers frmo 1 to 500. |
offset | Optional | Number of caches to skip from the beginning. Used in conjunction with limit for pagination. |
Validation
Parameter 'consumer_key' has invalid value: Consumer does not exist.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE
Required Parameter 'center' is missing.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE
Parameter 'status' has invalid value: 'JUNK' is not a valid cache type.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&status=JUNK
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&status=JUNK
Parameter 'type' has invalid value: 'aaa' is not a valid cache type.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&type=aaa
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&type=aaa
Parameter 'radius' has invalid value: '' is not a valid float number.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&radius=ABC
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&radius=ABC
Parameter 'terrain' has invalid value: '6'
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE&center=-37.8139|144.9634&terrain=6
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE&center=-37.8139|144.9634&terrain=6
Parameter 'difficulty' has invalid value: '6'
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&difficulty=6
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&difficulty=6
Parameter 'size2' has invalid value: 'Tiny' is not a valid cache size.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&size2=Tiny
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&size2=Tiny
Parameter 'limit' has invalid value: Has to be between 1 and 500.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=1000
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=1000
Parameter 'offset' has invalid value: Expecting non-negative integer.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&offset=-5
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&offset=-5
Examples
100 geocaches from Melbourne GPO with status Available.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=100&status=Available
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=100&status=Available
100 geocaches from Melbourne GPO with status Temporarily unavailable.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=100&status=Temporarily unavailable
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=100&status=Temporarily unavailable
10 geocaches within 10km from Melbourne GPO.
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=10&radius=10
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=10&radius=10
10 geocaches from Melbourne GPO with status Available and terrain between 1 and 2 (inclusive).
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=10&status=Available&terrain=1-2
https://geocaching.com.au/api/services/search/nearest/?consumer_key=YOUR_KEY_HERE¢er=-37.8139|144.9634&limit=10&status=Available&terrain=1-2
Data Fields Returned
Note that Geocaching Australia attempts to replicate the OKAPI response for ease of integration. All data fields will be returned by Geocaching Australia regardless of what was requested and fields that cannot be completed will be filled with default values.
The following OKAPI return array will not be included in the response: 'more':true|false
If the submission is successful a dictionary (array) named 'results' will be returned with a comma separated list of geocache codes.