contact us

Use the form on the right to contact us.

You can edit the text in this area, and change where the contact form on the right submits to, by entering edit mode using the modes on the bottom right.

633 Battery Street, Suite 100
San Francisco, CA 94111
USA

Use your iPhone/iPad as a movable window amid 360º experiences. Teleport into scenic spots, landmarks, events, hotels and more. License the Sphere SDK to enable the integration of our record, view and share spherical photography technology in your apps and websites. Info: support@theSphere.com

 

Sphericall.jpg

API

The Sphere API allows you to upload,

and manage your public spheres, and

to access all publicly posted content.

 

 

Running atop HTTP/HTTPS, our API accepts standard HTTP verbs to manipulate resources uniquely identified by URLs and responds in JSON. Below are links to specific parts of our API documentation.


Media Locations

Thumbnails

https://s3.amazonaws.com/tourwrist/tours/[sphere_id]/images/[thumbnail_style]/equirect.jpg

thumbnail_style:
:small => "160x80", 
:detail => "300x150", 
:large => "320x160", 
:large_retina => "640x320"

Sphere Cube Faces

https://s3.amazonaws.com/tourwrist/tours/[sphere_id]/images/[cube_face_style]/[front|back|left|right|top|bottom].jpg

cube_face_style:
:small => "512x512", 
:medium => "768x768", 
:large => "1024x1024", 
:hq => "2048x2048"

User Avatars

https://s3.amazonaws.com/tourwrist/users/[user_id]/images/[avatar_style]/avatar.jpg

avatar_style:
:large => "600x600" 

 


Request Headers

 

[“x-sphere-api-key”] - the sphere api key token. required for every request

[“x-sphere-api-access-token”] - the access token for the current user session. required for any personal api actions (editing your account, updating your pano). returned from the authentication and account creation requests.

[“x-sphere-device-locale”] - (OPTIONAL) user interface language on the client device. (ISO3166 code, e.g. “en_US”)

[“x-sphere-device-timezone”] - (OPTIONAL) current time zone of the client device. (IANA Time Zone Database name, e.g. “America/Los_Angeles”)

[“x-sphere-api-timestamp”] - (OPTIONAL, DEBUG ONLY) request timestamp. (Unix time, e.g. “1369634836”)

 


Sphere API Calls

Sharing Spheres

Required Headers: [x-sphere-api-key, x-sphere-api-access-token]

GET /api/v3/panos/[sphere_id]/share

Example Request Parameters:
{
“email” : “emailto@share.to”
}

Liking and Un-liking Spheres

[x-sphere-api-key, x-sphere-api-access-token]

POST /api/v3/panos/[sphere_id]/like

POST /api/v3/panos/[sphere_id]/unlike

Creating Spheres

Required Headers: [x-sphere-api-key, x-sphere-api-access-token]

POST /api/v3/panos

Example Request Parameters:
{
    “sphere” : {

“name” : “the best”,                      // required!
“tour_id” : 12345,                          // required!
“category_id” : 12345,                  // optional
“latitude” : 123.456,
“longitude” : 456.123,
“city” : “san francisco”,                  // optional, if lat/lon present
“state” : “california”,                      // optional, if lat/lon present
“zip_code” : 94107,                      // optional, if lat/lon present
“address” : “123 somewhere”,     // optional, if lat/lon present
“country” : “United States”,          // optional, if lat/lon present
“captured_date”:  1372799179,    // doesnt exist
“dhash”: “3a6c6565498da525”, // doesnt exist
“filename” : “IMG_0103.JPG”        // doesnt exist

    }

}

Uploading Equirects

Required headers [x-sphere-api-key, x-sphere-api-access-token]

This request is a 4 step process:

  1. Create sphere object
  2. Get signing parameters from server:  POST /api/v3/panos/[sphere_id]/request_equirect_upload
  3. Upload equirect directly to S3:  POST https://s3.amazonaws.com/tourwrist
  4. Confirm S3 upload with server:  POST /api/v3/panos/[sphere_id]/confirm_equirect_upload

Step 1 Example Response:
data = {
      post_to:                    "https://s3.amazonaws.com/tourwrist/", 
      signature:                 “sjfasjdifjasodfjidjf”, 
      acl:                            “ajsodifjsdfd”, 
      policy:                       “asdfasdfasdf”, 
      AWSAccessKeyId:     “asdjfsadjfoiajsdifjasdf”, 
      key:                           => "tours/12345/images/equirect.jpg"
}

Step 2:
POST to the “post_to” url returned in Step 1 response. 
The following parameters are required when posting to S3:

{
        :signature                          => data["signature"], 
        :acl                                    => data["acl"], 
        :policy                               => data["policy"], 
        :AWSAccessKeyId             => data["AWSAccessKeyId"], 
        :key                                   => data["key"],  
        :success_action_status     => 201,
        :file                                    => File.new(filepath, 'rb')
}

The request to S3 should be a multipart/form-data with the file parameter as the last parameter.

Step 3:
A response will be provided with the updated sphere information. Once the post has been made, processing will begin in the background and the sphere will be available within a few minutes.

Retrieving Spheres

GET /api/v3/panos
Required headers [x-sphere-api-key, x-sphere-api-access-token]

Example Request Parameters:
None currently

Example Success Response:
{
    "meta"=>{
        "status_code"=>200
    },
    "data"=>
        [
            {
                "id"=>45641, 
                "name"=>"io.jpg", 
                "latitude"=>"37.78336529922922", 
                "longitude"=>"-122.40355472564698", 
                "tour_id"=>17344, 
                "description"=>"", 
                "view_count"=>464, 
                "comments_count"=>2, 
                "location"=>"San Francisco, CA", 
                "address"=>"150 4th St", 
                "city"=>"San Francisco", 
                "state"=>"CA", 
                "zip_code"=>"94103", 
                "country"=>"USA", 
                "website"=>"", 
                "processed"=>true, 
                "active"=>true
            }, 
            {
                "id"=>44671, 
                "name"=>"Testef", 
                "latitude"=>"37.76667", 
                "longitude"=>"-122.4169", 
                "tour_id"=>16132, 
                "description"=>"Yay", 
                "view_count"=>51, 
                "comments_count"=>5, 
                "location"=>"San Francisco, CA", 
                "address"=>"1461 15th St", 
                "city"=>"San Francisco", 
                "state"=>"CA", 
                "zip_code"=>"94103", 
                "country"=>"US", 
                "website"=>nil, 
                "processed"=>true, 
                "active"=>true
            }
        ]
    }
}


Account API Calls

Uploading Avatars

Required headers [x-sphere-api-key, x-sphere-api-access-token]

This request is a 3 step process:

  1. Get signing parameters from server:  POST /api/v3/users/request_avatar_upload
  2. Upload avatar directly to S3:  POST https://s3.amazonaws.com/tourwrist
  3. Confirm S3 upload with server:  POST /api/v3/users/confirm_avatar_upload

Step 1 Example Response:
data = {
      post_to:                    "https://s3.amazonaws.com/tourwrist/", 
      signature:                 “sjfasjdifjasodfjidjf”, 
      acl:                            “ajsodifjsdfd”, 
      policy:                       “asdfasdfasdf”, 
      AWSAccessKeyId:     “asdjfsadjfoiajsdifjasdf”, 
      key:                           => "users/[user_id]/images/original/avatar.jpg"
}

Step 2:
POST to the “post_to” url returned in Step 1 response. 
The following parameters are required when posting to S3:

{
        :signature                          => data["signature"], 
        :acl                                    => data["acl"], 
        :policy                               => data["policy"], 
        :AWSAccessKeyId             => data["AWSAccessKeyId"], 
        :key                                   => data["key"],  
        :success_action_status     => 201,
        :file                                    => File.new(filepath, 'rb')
}

The request to S3 should be a multipart/form-data with the file parameter as the last parameter.

Step 3:
A response will be provided with the updated user information. Once the post has been made, processing will begin in the background and the resized avatar will be available shortly.

Creating Accounts

POST /api/v3/users

Required Headers: [x-sphere-api-key]

Example Request Parameters:
{
    “user” : {
    “email” : “somemail@somedomain.com”,
    “password”: “supersekret”,
    “password_confirmation”:”supersekret”,
    “username”:”supertester”,
    “first_name”:”best”,
    “last_name”:”tester” 
    }
}

Example Success JSON Response:
{
    "meta"=>
    {
    "status_code"=>200}, 
    "data"=>
    {
        "id"=>62026,
        "first_name"=>"test29.808319999503187",
        "last_name"=>"test53.71627480036412",
        "email"=>"testerstein91.93122106749331@test.com",
        "username"=>"testinstein77.56519495959427",
        "auth_token"=>"bb8b1428e930eb7ce67a4d3cfb7c6e51062423b",
        "profile_pic_url"=>"http://gravatar.com/avatar/a7b149851240b3ae5e462c597e514bfb.png?s=128&d=mm",
        "website"=>"",
        "description"=>"",
        "contact_email"=>"",
        "panos_count"=>0,
        "tours_count"=>1,
        "followers_count"=>0,
        "followings_count"=>0,
        "default_tour_id"=>75995
    }
    }
}

Example Failure JSON Response:
{
    "meta"=>
    {
    "status_code"=>400, 
    "details"=>"Error creating account."
    }, 
    "data"=>{
    "errors"=> {
        "email"=>["has already been taken"],
        "password"=>["doesn't match confirmation"],
        "first_name"=>["can't be blank"],
        "last_name"=>["can't be blank"],
        "username"=>["can't be blank"]
    }
    }
}

User Authentication

POST /api/v3/sessions

Required Headers: [x-sphere-api-key]

Example Request Parameters:
{
    “user” : {
    “login” : “somemail@somedomain.com”,
    “password”: “supersekret”
    }
}

Example Success JSON Response:
{
    "meta"=>{
    "status_code"=>200
    }, 
    "data"=>{
    "id"=>62026, 
    "first_name"=>"Best First Name Ever",
    "last_name"=>"test53.71627480036412",
    "email"=>"testerstein91.93122106749331@test.com",
    "username"=>"testinstein77.56519495959427",
    "auth_token"=>"aeb01f8fc987ba2bffa02edd8d52c58f67cacbf",
    "profile_pic_url"=>"http://gravatar.com/avatar/a7b149851240b3ae5e462c597e514bfb.png?s=128&d=mm",
    "website"=>"",
    "description"=>"",
    "contact_email"=>"",
    "panos_count"=>0,
    "tours_count"=>1,
    "followers_count"=>0,
    "followings_count"=>0,
    "default_tour_id"=>75995
    }
}

Example Failure JSON Response:
{
    "meta"=>{
    "status_code"=>400, 
    "details"=>"Invalid login credentials"
    }
}

Social Authentication

POST /api/v3/sessions

Required Headers: [x-sphere-api-key]

Example Request Parameters:
{
“uid” : “abc123”,
    “type”:”facebook”,
    “first_name”:”john”,
    “last_name”:”doe”,
    “email”:”john@domain.com”,
    “username”:”john123”,
    “token”:”socialresponsetoken”
}

types: [“facebook”, “google-oauth2”]

 


 

Questions or suggestions? Please contact us.