OpenCaching.com/api/geocache

GET a single Geocache

You can get a single geocache by adding the OX Code as a path parameter.  Any additional parameters can be added as query parameters.  For example: http://www.opencaching.com/api/geocache/OX1AABN

Defaults for parameters

description = html  - The description will be included in the response as HTML.

hint = true - The hint will be included in the response.

log_limit = 5 - The 5 most recent logs will be returned for the geocache.

GET a list of Geocache

Returns a list of geocaches that can be filtered by any of the optional parameters listed below.  Without any parameters the URL is http://www.opencaching.com/api/geocache/

Defaults for parameters

order_by - If a bbox or center parameter is present, then they are sorted by the distance from the center point or the center of the bbox. Otherwise the list will be sorted by the most recently published geocaches.

limit = 100 - The first 100 geocaches will be returned by default.

description =none - Description is not included by default to reduce the size of the response.

hint = false - Hint is not included by default to reduce the size of the response.

log_limit = 0 - Logs are not returned to reduce the size of the response.

Parameters

bbox=south,west,north,east

Returns a list of geocaches inside the specified bounding box sorted by the distance from the center of the box.

The parameters south latitude, west longitude, north latitude, east longitude define the edges of a bounding box.

Coordinates should be in decimal degrees

Use positive numbers for north latitude and east longitude and negative numbers of south latitude and west longitude.

The box cannot cross the 180° longitude line or the 90° or -90° points.

center=lat,lon

Returns a list of geocaches closest to the specified point side sorted by the distance from that point.

exclude_bbox=south,west,north,east

Limits returned geocaches to those not inside the specified bounding box.

The parameters south latitude, west longitude, north latitude, east longitude define the edges of a bounding box.

Coordinates should be in decimal degrees

Use positive numbers for north latitude and east longitude and negative numbers of south latitude and west longitude.

The box cannot cross the 180° longitude line or the 90° or -90° points.

oxcode=oxcode1,oxcode2,...

Limits returned geocaches to those caches that have an oxcode that is in the list.

name=name

Limits returned geocaches to those containing the string somewhere in their title. The search string does not have to start at the beginning of a word in the title.

difficulty=min_difficulty-max_difficulty

Limits returned geocache to those with a difficulty rating between min_difficulty and max_difficulty inclusive.

Min and max difficulty are decimal numbers that can range from 1 to 5

terrain=min_terrain-max_terrain

Limits returned geocache to those with a terrain rating between min_terrain and max_terrain inclusive.

Min and max terrain are decimal numbers that can range from 1 to 5

awesome=min_awesomeness-max_awesomeness

Limits returned geocache to those with a awesomeness rating between min_awesomeness and max_awesomeness inclusive.

Min and max awesomeness are decimal numbers that can range from 1 to 5

size=min_size-max_size

Limits returned geocache to those with a size rating between min_size and max_size inclusive.

Min and max size are decimal numbers that can range from 1 to 5

found=true/false

A user must be logged in for this parameter to have any affect.

found = true:
Only geocaches the user has already logged as found will be returned.

found = false:
Only geocaches the user has not already logged as found will be returned.

found not specified:
Both geocaches the user and marked as found and those not marked as found will be return.

type

List of the types of geocaches to be returned. If no type parameter is specified, all types are returned. Otherwise, only the listed types are returned.

Traditional Cache

Multi-cache

Unknown Cache - aka Puzzle

Virtual Cache

status

List of the statuses of geocaches to be returned. If no status parameter is specified, then only active geocaches are returned. Otherwise, only geocaches that have the status matching what is listed are returned.

Active

Archived

Review - currently this can not be used in conjunction with Active and/or Archived.

See User API for Draft status.

limit=limit

Sets the maximum number of geocaches that will be returned. Can be between 1 and 5000. Defaults to 100 if no limit is specified.

hard_limit=true/false

hard_limit = true:
If more geocaches fit the criteria than what can be returned before reaching the the limit, then an error (HTTP error 413) is returned instead of any geocaches.

hard_limit = false or not specified:
If more geocaches fit the criteria than what can be returned before reaching the limit, then the closest geocaches to the center of the query are returned.

description=none/user/html

description = html:
Cache descriptions are returned as HTML for all geocaches.

description = user:
Cache descriptions are returned as entered by the geocache owner entered it for all geocaches.

description = none:
Cache descriptions are not returned.

Avoid fetching descriptions unless you really need the description for every geocache. Getting the geocache descriptions can triple (or more) the size of the returned data. When possible get a list of geocaches without descriptions, and then get the descriptions for individual geocaches as necessary.

hint=true/false

hint = true:
Hints are returned for all geocaches.

hint = false:
Hints will not be returned

log_limit=log_limit

The number of logs that will be returned with each geocache.

log_comment=true/false

This parameter can be used to reduce the amount of data that is returned.  This parameter can be used if need to know if the geocache has had any recent Found or Did Not Find logs, but don't care about the description.

log_comment = true:
Logs that are returned for the geocache will include the log comment.

log_comment = false:
No comment will be included for logs that are returned as part of the geocache.

hidden_by=user_id1,user_id2,user_id3,...

Return only geocaches that were hidden by the specified users.  This should be the user_id and not their handle.

tags

List of tags used to filter the geocaches that are returned.  This is used when you want the geocache to match at least one of the tags in the list.  Comma separated list of strings. 

required_tags

List of tags used to filter the geocaches that are returned.  Only geocaches that have all the tags specified will be returned.  Comma separated list of strings. 

exclude_tags

List of tags used to filter the geocaches that are returned.  Only geocaches that do not have any of the tags specified will be returned.  Comma separated list of strings.

series

If this parameter is not supplied then it will default to returning the series information for the geocaches.

series = none:
The series information will not be returned for the geocaches.

series = series_id1,series_id2,... etc:
Only geocaches that are part of the series will be returned.

order_by=center/published_dttm

If a bbox or center parameter is present, then they are sorted by the distance from the center point or the center of the bbox. Otherwise the list will be sorted by the most recently published geocaches.

order_by = center:
If there is a bbox or center point provided then you can use order_by = center to sort the geocaches that are returned by the center of the bbox or by the center point.

order_by = published_dttm:
This will sort the geocaches that are returned by when they were published from the newest caches to the oldest.

ifmod

Unix timestamp.

Only return the json or gpx response if any of the geocache data, images, or logs have been modified since the specified timestamp. If anything has been changed the full response (not just what has changed) will be returned.

We use this for syncing so that we are only updating the data that is necessary to reduce the time it takes to sync.