Introduction

The Podium REST API is used to securely gather information for a single app. All requests are made to the secure API URL, and most return a JSON response. All of this information is yours, for you to upload to your own app. The Podium platform acts as a CMS back end for your app. Each API call can also have details included to identify details such as what page the user is on, the OS, or type of device they are using. More details here.

See below for more details.

Building the Request
Events
GET events
Returns 20 events.
Resource URL
https://podium.io/api/v1/events/
Parameters
request

required
Specifies the type of request.

close will return the events geographically closest to the specified location, regardless of the start date. lat and long parameters are required with this option.

soon will return upcoming events in chronological order, regardless of the location.

all will return all events in chronological order by the start date.

single will return a single event by id, specified by the 'id' parameter.

categories will return a list of your event categories.

Example values: close, soon, all, single, categories

count

optional
Specifies the number of events to attempt to retrieve, up to a maximum of 200. If not specified, 20 events will be returned.

Example values: 50

category

optional
Returns only events from the specified category. If not specified, events from any and all categories will be returned. Note: Be sure to encode spaces (%20) before you hash the URL.

Example values: comedy, music, theatre

lat

optional
Used to specify the current latitude of the app making the request. If request is close, this parameter is required.

Example values: 37.421641

long

optional
Used to specify the current longitude of the app making the request. If request is close, this parameter is required.

Example values: -122.085502

id

optional
Specifies the id of a single event you want to look up. Will return distance to event if lat and long are specified and event's location coordinates are specified. Required if request is set to single.

Example values: 1024568

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Request
GET
https://podium.io/api/v1/events/?request=close&count=20&lat=37.421641&long=-122.085502
Locations
GET locations
Returns 20 closest locations.
Resource URL
https://podium.io/api/v1/locations/
Parameters
request

required
Specifies the type of request.

close will return the events geographically closest to the specified coordinates, regardless of the start date. lat and long parameters are required with this option.

all will return all locations in alphabetical order.

single will return a single event by id, specified by the 'id' parameter.

categories will return a list of your event categories in alphabetical orders.

Example values: close, all, single, categories

count

optional
Specifies the number of locations to try and retrieve, up to a maximum of 200. If not specified, 20 locations will be returned.

Example values: 20

category

optional
Returns only locations from the specified category. If not specified, locations from any and all categories will be returned. Note: Be sure to encode spaces (%20) before you hash the URL.

Example values: dining, entertainment, shows

lat

optional
Used to specify the current latitude of the app making the request. This parameter is required if request is close.

Example values: 37.421641

long

optional
Used to specify the current longitude of the app making the request. This parameter is required if request is close.

Example values: -122.085502

id

optional
Specifies the id of a single event you want to look up. Will return distance to event if lat and long are specified and event's location coordinates are specified. Required if request is set to single.

Example values: 1024568

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Request
GET
https://podium.io/api/v1/locations/?request=close&count=20&lat=37.421641&long=-122.085502
Notifications
GET notifications
Returns 20 latest notifications.
Resource URL
https://podium.io/api/v1/notifications/
Parameters
request

optional
Specifies the type of request.

all will return all locations in alphabetical order.

categories will return a list of your event categories in alphabetical orders.

Example values: all, categories

count

optional
Specifies the number of notifications to try and retrieve, up to a maximum of 200. If not specified, 20 notifications will be returned.

Example values: 40

category

optional
Returns only notifications from the specified category. If not specified, locations from any and all categories will be returned. Note: Be sure to encode spaces (%20) before you hash the URL.

Example values: important, news, updates

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Requests
GET
https://podium.io/api/v1/notifications/
GET
https://podium.io/api/v1/notifications/?count=40
Info Pages
GET page
Returns one HTML page.
Resource URL
https://podium.io/api/v1/page/
Parameters
xid

required
A 20 character value that specifies the XID of the page you are requesting. This value is available under the "info pages" section of the app listed in your account.

Example values: I3hgXvRg4cxk8r1Z85U5

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Requests
GET
https://podium.io/api/v1/page/?xid=I3hgXvRg4cxk8r1Z85U5
Info Blocks
GET info
Returns an information block.
Resource URL
https://podium.io/api/v1/info/
Parameters
request

required
Specifies the type of request.

all will return all info blocks in alphabetical order by title.

categories will return a list of your info block categories in alphabetical orders.

single will return a single info block, specified by the 'xid' parameter.

Example values: all, categories, single

count

optional
Specifies the number of info blocks to try and retrieve, up to a maximum of 200. If not specified, 20 notifications will be returned.

Example values: 40

category

optional
Returns only info blocks from the specified category. If not specified, locations from any and all categories will be returned. Note: Be sure to encode spaces (%20) before you hash the URL.

Example values: important, news, updates

xid

optional
A 20 character value that specifies the XID of the info block you are requesting. This value is available under the "info blocks" section of the app listed in your account. This value is required if "request" is set to single.

Example values: I3hgXv4g4cxk8d1Z85U5

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Requests
GET
https://podium.io/api/v1/info/?request=all
GET
https://podium.io/api/v1/info/?request=single&xid=I3hgXv4g4cxk8d1Z85U5
Sponsors
GET sponsors
Returns 20 sponsors.
Resource URL
https://podium.io/api/v1/sponsors/
Parameters
start

optional
Specifies where to start the sponsors. Useful for pagination in your app. Default is 0.

Example values: 40

count

optional
Specifies the number of sponsors to try and retrieve, up to a maximum of 200. If not specified, 20 sponsors will be returned.

Example values: 40

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Requests
GET
https://podium.io/api/v1/sponsors/
GET
https://podium.io/api/v1/sponsors/?count=40
Exhibitors
GET exhibitors
Returns 20 exhibitors.
Resource URL
https://podium.io/api/v1/exhibitors/
Parameters
start

optional
Specifies where to start the exhibitors. Useful for pagination in your app. Default is 0.

Example values: 40

count

optional
Specifies the number of exhibitors to try and retrieve, up to a maximum of 200. If not specified, 20 exhibitors will be returned.

Example values: 40

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Requests
GET
https://podium.io/api/v1/exhibitors/
GET
https://podium.io/api/v1/exhibitors/?count=40
Event Schedules
GET eventSchedules
Returns 20 schedule items.
Resource URL
https://podium.io/api/v1/eventSchedules/
Parameters
start

optional
Specifies where to start the items on the schedule. Useful for pagination in your app. Default is 0.

Example values: 40

count

optional
Specifies the number of items to try and retrieve, up to a maximum of 200. If not specified, 20 items will be returned.

Example values: 40

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Requests
GET
https://podium.io/api/v1/eventSchedules/
GET
https://podium.io/api/v1/eventSchedules/?count=40
Send an Email
POST email
Sends an email from the user to the admin of the app. Information must be filled in in the Global Settings for the app for this to work. If the redirect pages are not set, the API will return a json output. If an error occurs, the API will return a json output.
Resource URL
https://podium.io/api/v1/email/
Parameters
from_name

required
A value collected from the user sending the email. This is the name of the sender.

Example values: Sergey

from_email

required
A value collected from the user sending the email. This is the email address of the sender.

Example values: anon@gmail.com

subject

optional
The subject of the email. If this is not specified, it will default to "From Your Podium App".

Example values: Comments from our mobile app

type

optional
The type of email you are sending. Default is html.

Example values: text, html

redirect

optional
Set to true, this option will cause the api to redirect to your success or error info pages set with the parameters below. If set to true, success and error parameters are required. If the pages are not set, the response will be json. Set to false, the output will return json, either an error or a sucess status message. Default is false.

Example values: true, false

success

optional
The info page to redirect to for a successful sent email.

Example values: I3hgXvRg4cxk8r1Z85U5l

error

optional
The info page to redirect to for a problem sending the email.

Example values: s3hgevRg4cxkcsr1Z85U5

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Requests
POST
https://podium.io/api/v1/email/
Global Information
GET global
Returns global information about the app. This is information that you specify in the Global section of your application.
Resource URL
https://podium.io/api/v1/global/
Parameters
request

required
Specifies the type of request.

protected will return a code for the page specified by the page parameter. If no page is specified, this will return an array of all protected pages and codes.

Example values: protected

page

optional
Specifies the page for a protected specific code request.

Example values: admin

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Example Requests
GET
https://podium.io/api/v1/global/?request=protected
GET
https://podium.io/api/v1/global/?request=protected&page=admin
Data Storage
GET data

Podium stores your data as objects containing JSON compatible key-value pairs. You can think of Podium data storage as your app's cloud database where each object is a row in that database.

Using Podium Data Storage you can perform GET and QUERY operations.

Resource URL
https://podium.io/api/v1/data/
GET Parameters
You can send GET parameters in the form of json compatible key-value pairs.
request

required
Specifies the type of request.

The following documentation will discuss the various types of requests.

Example values: get, query

(analytics)

optional
You can specify certain parameters to store in your Podium account for analytics such as OS or type of device. For more details, visit this page.
Request: get
"get" requests return a single json object.
tableID (string)

required
Specifies the table id from which you are requesting data. You can get this value from your tables page.

Example values:tXAvBuAbx9, cmAAfbuAPc

objectID (string)

required
Specifies objectID from which you are requesting data. This is a unique value for each row in your table. If you need to return more than one object, use a "query" request.

Example values:dkEsXkDan, eWdXiMxAqk

columns (array)

optional
Specify the column names you wish to retreive information from. Must be specified as a JSON encoded array. If this is not specified, Podium will return the entire object. These should be columns you already have set up in a table.

Example values: [ "itemNumber", "itemPrice", "comments" ]

Request: query
"query" requests return multiple json objects including the objectID for each. This request can be used to filter and sort through your data, much like a SQL query.
tableID (string)

required
Specifies the table id from which you are requesting data. You can get this value from your tables page.

Example values:tXAvBuAbx9, cmAAfbuAPc

columns (array)

optional
Specify the column names you wish to retreive information from. Must be specified as a JSON encoded array. If this is not specified, Podium will return the entire object. These should be columns you already have set up in a table.

Example values: [ "itemNumber", "itemPrice", "comments" ]

greaterThan (object)

optional
Argument to filter the results of objects returned by your query. Parameters must be specified as a JSON encoded object. Parameters may be specified as a string, integer, or just about any English textual datetime, for example "August 19, 2004".

Example values: { "score" : 10, "date" : "August 19, 2004" }

lessThan (object)

optional
Argument to filter the results of objects returned by your query. Must be specified as a JSON encoded array. May be specified as a string, integer, or just about any English textual datetime, for example "August 19, 2004".

Example values: { "score" : 10, "date" : "August 19, 2004" }

equalTo (object)

optional
Argument to filter the results of objects returned by your query. Must be specified as a JSON encoded array. May be specified as a string, integer, or just about any English textual datetime, for example "August 19, 2004".

Example values: { "score" : 10, "date" : "August 19, 2004" }

notEqualTo (object)

optional
Argument to filter the results of objects returned by your query. Must be specified as a JSON encoded array. May be specified as a string, integer, or just about any English textual datetime, for example "August 19, 2004".

Example values: { "score" : 10, "date" : "August 19, 2004" }

limit (int)

optional
Argument to limit the number of results of objects returned by your query. Must be specified as an integer. By default, 100 objects will be returned, but specifying anything from 1 to 1,000 is a valid limit.

Example values: 10, 20

order (object)

optional
Argument to order the results of objects returned by your query. Must be specified as a single key-value pair in a JSON encoded array, where the value is either "asc" or "desc". Multiple values may be used.

Example values: { "score" : "desc" }

Example Requests
GET
https://podium.io/api/v1/data/?request=get&objectID=dekEsXkDam
Sending the Request
Requirements
All requests must include the requested resource, your public key, a timestamp, and an nonce hash. The following documentation will walk you through the steps to generate your request. The following example will use a request for the events closest to a specified location.
1. Start with the Resource URL
https://podium.io/api/v1/events/
This resource URL is what you are targeting to request information from the Podium API. This is the URL you will use to build your request.
2. Add parameters.
https://podium.io/api/v1/events/?request=close&lat=37.421641&long=-122.085502
Set the request to "close", and then gather and include the device's current coordinates.
Note: Place the parameters in the order listed on this page.
3. Add your public key and timestamp. (public_key, date)
https://podium.io/api/v1/events/?request=close&lat=37.421641&long=-122.085502 &public_key=KcIRoGC3WHdR29JhfN1cg&date=905144400
ATTENTION: Never send your private key over the wire. It should only be used to create your nonce hash.
Using UTC time, send the device's current timestamp.
Note: If you are having issues with the timestamp, use this, or this to gather your UTC time.
4. Add hash. (nonce)
https://podium.io/api/v1/events/?request=close&lat=37.421641&long=-122.085502 &public_key=KcIRoGC3WHdR29JhfN1cg&date=905144400 &nonce=fd1552a4ce51aefe819c7196760b672f4a8c3f76c454ece62b9985c8bec40c1e

To get your nonce hash, you must create a hash-based message authentication code (HMAC) by SHA256 hashing your URL up to this point using your private key. In this example,

Public Key: KcIRoGC3WHdR29JhfN1cg
Private Key: 2ZWTeKi47fZwVPp6ds5nxUtvsvS3Hm2FLkadbcA8U2

The resulting hash is fd1552a4ce51aefe819c7196760b672f4a8c3f76c454ece62b9985c8bec40c1e

Creating your nonce (This will vary based on the language you use):
Note: Take notice when copying and pasting the following code, it includes spaces in the URLs for web readability. You must remove these spaces or the code will not work!

For PHP:

<?
    // set variables
    $public_key = 'KcIRoGC3WHdR29JhfN1cg';
    $private_key = '2ZWTeKi47fZwVPp6ds5nxUtvsvS3Hm2FLkadbcA8U2';
    $time = time();
    
    // set data var to the URL you have built so far
    $data = 'https://podium.io/api/v1/events/?request=close &lat=37.421641&long=-122.085502&public_key='.$public_key.' &date='.$time;
	
    // generate hash
    $hash = hash_hmac('sha256', $data, $private_key);
    
?>

For JavaScript (Appcelerator):

Note: You must include a third party script to generate the hmac hash. The following code uses crypto-js, hosted on google code, available here.

    // include cryptography script
    Ti.include("../../includes/CryptoJS_v3.1.2/rollups/hmac-sha256.js");
    
    // set variables
    var url = 'https://podium.io/api/v1/events/';
    var public_key = 'KcIRoGC3WHdR29JhfN1cg';
    var private_key = '2ZWTeKi47fZwVPp6ds5nxUtvsvS3Hm2FLkadbcA8U2';
		 		
    var currentTime = new Date();
    var time = Math.round((currentTime.getTime())/1000);
 		
    var data = url + '?request=close &lat=37.421641&long=-122.085502 &public_key=' + public_key + '&date=' + time;
    var hash = CryptoJS.HmacSHA256(data, private_key);

For Lua (Corona):

    -- set variables
    local public_key = "KcIRoGC3WHdR29JhfN1cg"
    local private_key = "2ZWTeKi47fZwVPp6ds5nxUtvsvS3Hm2FLkadbcA8U2"
    local t = os.date( '*t' )
    local time = os.time( t ) 
    
    -- set data var to the URL you have built so far
    local data = "https://podium.io/api/v1/events/?request=close &lat=37.421641&long=-122.085502&public_key=" .. public_key .. " &date=" .. time
    
    -- generate hash
    local crypto = require "crypto"
    local hash = crypto.hmac( crypto.sha256, data, private_key )

5. Send the request.
https://podium.io/api/v1/events/?request=close&lat=37.421641&long=-122.085502 &public_key=KcIRoGC3WHdR29JhfN1cg&date=905144400 &nonce=fd1552a4ce51aefe819c7196760b672f4a8c3f76c454ece62b9985c8bec40c1e
Handling the Response
Overview
The Podium REST API will return a json response with either an OK status, or an error code. Error codes will provide information as to what went wrong with the request. View examples below.
Example Response:
{
    "status":{
    	"message":"OK","code":100
    },
    "events":[
    	{
            "event_title":"Comedy Show",
            "event_start_date":"Mar 7 2013 5:30 pm",
            "event_end_date":"Mar 7 2013 6:30 pm",
            "event_category_1":"Comedy",
            "event_category_2":"Theatre",
            "event_category_3":null,
            "event_category_4":null,
            "event_category_5":null,
            "event_category_6":null,
            "page":"EdC4WL4cLpI34DHx286B",
            "event_description":"Best comedy show ever!",
            "location_name":"Stage 16",
            "location_address":null,
            "location_address2":null,
            "location_city":null,
            "location_state":null,
            "location_zip":null,
            "location_country":null,
            "location_lat":"40.7624460",
            "location_lng":"-111.8743240",
            "location_description":"North Stage",
            "location_distance":{
                "ft":3524860,
                "mi":667.6
            }
        },
        {
            "event_title":"Magic Show",
            "event_start_date":"Mar 8 2013 4:30 am",
            "event_end_date":"Mar 8 2013 6:30 am",
            "event_category_1":"Shows",
            "event_category_2":"On Stage",
            "event_category_3":"Theatre",
            "event_category_4":null,
            "event_category_5":null,
            "event_category_6":null,
            "page":"",
            "event_description":"Best magic show ever!",
            "location_name":"Stage 4",
            "location_address":null,
            "location_address2":null,
            "location_city":null,
            "location_state":null,
            "location_zip":null,
            "location_country":null,
            "location_lat":"39.6784870",
            "location_lng":"-104.9221420",
            "location_description":"Magical Stage",
            "location_distance":{
                "ft":5679485,
                "mi":1075.7
            }
        }
    ]
}
Example Error:
{
    "errors":{
    	"message":"Forbidden",
        "code":403,
        "details":"Timestamp Out of Range"
    }
}
Status/Error Codes
Code: 100
Message: OK
Description: Success!
Code: 201
Message: No Data
Description: There is no data available to display.
Code: 401
Message: Unauthorized
Description: Authentication credentials were missing or incorrect.
Code: 402
Message: Missing Parameter
Description: The request is missing at least one required parameter.
Code: 403
Message: Forbidden
Description: The request is understood, but has been refused access or is not allowed.
Code: 404
Message: Not Found
Description: The request is invalid or the resource requested does not exist.
Code: 405
Message: Limit Reached
Description: The request has reached or exceeded an update or request limit.
Code: 406
Message: Not Acceptable
Description: An invalid format is specified by the request. This will also be returned if a value is out of range, like the count parameter, or an incorrect category is specified.
Code: 500
Message: Internal Server Error
Description: Something is broken. Please let us know so that we can investigate.
Code: 502
Message: Bad Gateway
Description: The servers are down or are being upgraded.
Code: 503
Message: Service unavailable
Description: The servers are up, but overloaded with requests. Try again later.