https://geocha-production.herokuapp.com/api/v2/maps/MAP_ID?auth_token=AUTH_TOKEN

Important note

For your application, you should have each user go through an authentication and authorization flow in order to receive a valid auth_token.

Request Limits

Be nice. If you're sending too many requests too quickly, we'll send back a 503 error code (server unavailable). Each user is limited to 5000 requests per hour per auth_token. Whenever possible authenticate users so that limits dont´t count on your own auth_token.

Structure

JSON response

The meta key contains a code key and in case an error occured it contains additional information about the error. For index requests the meta key contains pagination information. The data key is where you find the data you requested. This can be a dictionary or an array. Each API request receives a JSON response. The basic structure of a response looks like:

{
    "data": {
        "id": 63921,
        "name": "Bill Hicks",
        "screen_name": "billhicks",
        "url": "http://www.billhicks.com",
        "location": "Little Rock, Arkansas",
        "profile_picture": null,
        "picture_url": null,
        "header_picture": null,
        "about": null,
        "counts": {
            "maps": 12
        }
    },
    "meta": {
        "code": 200
    }
}

Pagination

page	(optional) Specifies the page of results to retrieve.
count	(optional) The number of potential results to retrieve per page. This value has a maximum of 50 for most resources.
max_id/min_id	To use max_id correctly, an application’s first request to a endpoint should only specify a count. When processing this and subsequent responses, keep track of the lowest ID received. This ID should be passed as the value of the max_id parameter for the next request, which will only return objects with IDs lower than or equal to the value of the max_id parameter.

Media upload

The image passed should be base64 encoded.

Authentication

Authentication is handled by an authentication token. Authentication tokens may expire at any time in the future.

Receiving an auth_token

To receive an auth_token with HTTP Basic Authentication you have to make a get request to:

curl -v -u john.doe@example.com:PASSWORD -X GET https://geocha-production.herokuapp.com/api/v2/authentication

To receive an auth_token with url parameters user[email] and user[password] you have to make a get request to:

curl -v -X GET https://geocha-production.herokuapp.com/api/v2/authentication?user%5Bemail%5D=john.doe%40example.com&user%5Bpassword%5D=PASSWORD

Your response will look like this:

{
    "data": {
        "id": 63921,
        "name": "Bill Hicks",
        "screen_name": "billhicks",
        "url": "http://www.billhicks.com",
        "location": "Little Rock, Arkansas",
        "profile_picture": null,
        "picture_url": null,
        "header_picture": null,
        "about": null,
        "counts": {
            "maps": 12
        },
        "time_zone": null,
        "language": null,
        "auth_token": "VAxoQv9awynTek6K3p7L"
    },
    "meta": {
        "code": 200
    }
}

Keep the received auth_token securely for later requests. On subsequent requests simply pass the auth_token as part of your data and you will be automatically authenticated.

You can pass authentication tokens as part of the url but authentication tokens are best send in the request header

curl -v -X GET -H 'X-AUTH-TOKEN': 'VAxoQv9awynTek6K3p7L' https://geocha-production.herokuapp.com/api/v2/maps/MAP_ID

curl -v -X GET https://geocha-production.herokuapp.com/api/v2/maps/MAP_ID?auth_token=VAxoQv9awynTek6K3p7L

Collaboration and privacy

Visibility — Public and private

When you create new uebermaps, your uebermaps are public by default; anyone can view your uebermap. Should you choose to protect your uebermap, you can do so through the visibility parameter.

Possible values
public	Anyone can see your uebermap.
link	Your uebermap is private but you can share it with a secret link.
private	Your uebermap is private.

Updating the visibility of an uebermap:

curl -X PUT -d [map][visibility]=private https://geocha-production.herokuapp.com/api/v2/maps/9529942

Access

With each uebermap you create you get full control over the way that people interact with the resources on your uebermap. People that visit your uebermaps are either:

Role
owner	The person that created this uebermap.
admin	Can only be invited by the owner of this uebermap.
editor	Invited people that have specific access to this uebermap and the resources on it.
visitor	Anyone else that visits your uebermap.

You can set the access rights for spots, events, comments, photos and the uebermap itself individually for invited editors and visitors.

Set access to a resource by following this schema: <ACCESS_VALUE>.<RESOURCE> f.e. can_propose.spots.

Possible values

map (editors only)
administer	Can edit title, header photo and description of this uebermap.
none	Can only view this uebermap.

collaborators (editors only)
administer	Can invite new editors to this uebermap.
none	Can not invite new editors to this uebermap.

spots, events, comments, attachments
administer	Can create, edit, delete your own and anyone elses resources f.e. comments.
create	Can create the specified resource but only edit and delete own resources.
propose	Can propose the specified resource and only edit and delete own resources.
none	Can only view resources on this uebermap.

The following snippet is a valid map settings json object.

{
    "map_settings": {
        "editor_access": [
            "can_none.map",
            "can_create.spots",
            "can_create.events",
            "can_create.comments",
            "can_create.attachments",
            "can_create.collaborators"
        ],
        "visitor_access": [
            "can_none.map",
            "can_none.spots",
            "can_none.events",
            "can_create.comments",
            "can_create.attachments",
            "can_none.collaborators"
        ],
        "respotting_to_this_map": false
    }
}

Example

Updating the map settings of an uebermap by sending access values comma separated for editors and visitors:

curl -X PUT -d [map][map_settings][editor_access]=can_administer.map, can_create.spots, can_administer.events, can_administer.comments, can_administer.attachments, can_propose.collaborators 
-d [map][map_settings][editor_access]=can_none.map, can_propose.spots, can_propose.events, can_create.comments, can_create.attachments, can_none.collaborators https://geocha-production.herokuapp.com/api/v2/maps/9529942

Moderating proposals

By creating an uebermap you have full control to approve, delete, or edit the spots, events, photos and comments left on your uebermap. Moderation is a feature in uebermaps.com that allows you to prevent spots, events, photos or comments from appearing on your uebermap without your express approval. Moderation can be very useful in addressing spam, but it is also a great application for builing map communities.

Approving a resource

To approve a spot, event, photo or comment simply provide a status parameter with the value of 'approved' on a PUT request:

curl -X PUT -d [spot][status]=approved https://geocha-production.herokuapp.com/api/v2/spots/5829942

Unapproving a resource

To unapprove a spot, event, photo or comment simply send a DELETE request to the specified resource:

curl -X DELETE https://geocha-production.herokuapp.com/api/v2/spots/5829942