FANDOM


Resighting has a RESTful JSON API. The API requires an Access Token granted using OAuth 2.0 for authorisation.

Creating an ApplicationEdit

Before you can begin calling API methods you must create an Application. An Application represents your integration with Resighting - for example it could represent your website that accesses Resighting data or an iPhone App that you are developing.

It is easy to create a new Application on the Resighting developer website .

User AuthorisationEdit

Once you have created your Application you need to get an Access Token to pass to each API method. An Access Token allows your Application to access Resighting on behalf of one user. For example, if your Application represents an iPhone App that uses Resighting data, you will create an Application for your iPhone App and then each user who uses your iPhone App will have to authorise with the Resighting API and each will have a distinct Access Token.

See the Authorisation Guide for details.

API MethodsEdit

The following API methods are available once you have an access token to pass to them.

Note that all API access is by SSL only, to https://resighting-api.appspot.com and not to https://www.resighting.com.

Prior to August 2013, all API access was to https://resighting.appspot.com. This URL remains active, however we recommend switching over to https://resighting-api.appspot.com when possible.

Method Description
CreateLocator Create a locator.
CreateLocatorSighting Add a Sighting to a locator.
CreateSighting Create a Sighting.
GetDailySighting Get the Sighting that appears daily on the Resighting homepage.
GetSighting Get details of a Sighting.
GetUser Get details of a user.
GetUserStatistics Get the statistics for a particular user.
ListLocatorSightings List a particular Locator’s Sightings.
ListLocators List all locators.
ListResightings

List resightings of a Sighting.

ListSightingLocators List the Locators that a Sighting has been submitted to.
ListSightings List Sightings.
ListUserCountryStatistics List the countries that a user has sighted in.
ListUserLocalityStatistics List the localities that a user has sighted in.
ListUserLocators List Locators that a particular user is a member of.
ListUserSightings List a particular user’s Sightings.
Meta Get metadata about the API and Resighting.
RemoveLocatorSighting Remove a Sighting from a locator.
ResightSighting Resight an existing Sighting.
UpdateSighting Update an existing Sighting.
Upload Upload an image to Resighting.
UploadUrl Create an image upload url.
User

Get details of the current user, i.e. the owner of the access token.

API ObjectsEdit

Each API method returns an object upon completion containing the results of the operation. The table below lists all the available objects.

Object Description
Address Encapsulates a locality and a country.
AgedSightings Counts of a user's Sightings made by day and year.
Altitude Contains the altitude of a Sighting.
Avatar Represents a user's avatar image.
Centre Encapsulates the centre-position of the user’s world.
Error Contains information about an error that occurred during a call to the API.
Evidence Represents a Sighting's evidence image.
FavouriteLocality Describes a user's favourite locality, i.e. the locality they have most often sighted in.
HighestSighting Describes the highest Sighting made by a particular user.
LastNewCountry Describes the last new country that the user sighted in.
LastNewLocality Describes the last new locality that the user sighted in.
LastSighting Encapsulates details of the user’s last (most recent) Sighting.
List Returned by list methods containing a list of results of other object types.
Location Encapsulates a longitude, a latitude and the accuracy of the two.
Locator Contains the details of a Locator.
LocatorMember Represents a member of a Locator.
LocatorSighting Represents a Sighting submitted to a Locator.
Meta Contains metadata about the Resighting website and the API.
MostNumSightingsInDay Describes the most number of Sightings ever made by a user in one day.
Settings Contains the current profile settings for a user.
Sighting Contains details of a Sighting.
SightingRef A reference to a Sighting - its unique key.
Upload Contains a unique Id that identifies an uploaded image.
UploadUrl Contains the url to which an image may be uploaded.
User Represents a user of Resighting.
UserCountryStats The statistics for a particular country for a particular user.
UserLocalityStats The statistics for a particular locality for a particular user.
UserPrivateStats Encapsulates a user’s private statistics - those statistics that can only be retrieved by the user.
UserPublicStats Encapsulates a user’s public statistics - those statistics that can be retrieved by anyone.
UserStats Contains the public and private statistics for a particular user.

Base DatatypesEdit

The API objects use the following base datatypes for their attributes.

ErrorsEdit

If an error occurs during invocation of an API method, an HTTP status 4xx or 5xx is returned and the response body will contain an Error object. See Errors for a full list of possible errors.

SandboxingEdit

API methods that change data in Resighting (i.e. create or update methods) can run in sandbox mode. In this mode they perform as much validation of your request as they can before returning without making any changes to the datastore. The object returned by the API will contain dummy data. This can be very useful when testing your integration with Resighting.

Image ResizingEdit

Two objects returned by API methods - the Avatar and Evidence objects contain urls where an image can be requested. It is possible to request the images in different sizes and also cropped to a square. See Images for more information.

HTTP OptionsEdit

All API methods support the HTTP OPTIONS method, which returns in each case help on using the API method in question. For example, making the following request of the API:

curl https://resighting-api.appspot.com/api/1/user -X OPTIONS

returns the result:

[
    {
        "method": "GET",
        "description": "Return the details of the user the specified access token is for",
        "parameters": [
            {
                "name": "access_token",
                "type": "string(32)",
                "required": true,
                "description": "A valid access token previously granted via the OAuth 2.0 endpoints"
            }
        ],
        "returns": "A JSON-encoded User entity or Error entity"
    },
    {
        "method": "OPTIONS",
        "description": "Returns the options available for this resource",
        "returns": "This help text"
    }
]

API Client (apiclient.py)Edit

A simple Python API client script exists that makes it easy to invoke Resighting API methods from the command line. While it is perfectly possible to use curl for this, apiclient.py adds a simple layer of abstraction and documentation on top, so for example you don't need to remember all the urls.

We use it for testing here at Resighting and we felt it may be useful to you too so it can be downloaded from our public Resighting Utils GitHub repository https://github.com/mdneale/resighting-utils. For documentation see apiclient.py.

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.