Localist API

Overview

The Localist API is a simple HTTP-based interface. Standard HTTP calls will return JSON your application can use.

It stands to reason that Localist’s API is the most powerful calendar API in the world (muahahah!).

Your use and access to the API is expressly conditioned on your compliance with the policies, restrictions and other provisions related to the API set forth in our API Terms of Use and the other documentation we provide you. You must also comply with the restrictions set forth in the Localist Terms of Service and the Localist Privacy Policy, in all uses of the API. If Localist believes that you have or attempted to violate any term, condition or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.

Usage

All the resources described are available under http://CALENDAR-URL/api/2/. A simple HTTP GET request can be made to retrieve results. Requests that change data require a HTTP POST or HTTP PUT. Requests that remove data require a HTTP DELETE.

Note: All examples need to have your calendars’s URL in place of the CALENDAR-URL placeholder. For instance, if your calendar is at http://calendar.example.edu, the API is located at http://calendar.example.edu/api/2/.

Important: http://CALENDAR-URL/api/2/ is the starting point of the API. It will not return anything on its own. The API needs to know what type of content to return, which is outlined in the Resources section.

Versioning

The API has a version number, currently 2.1. The minor version is incremented whenever we make changes to either the parameters or output that are incompatible or may require special attention.

When possible, new resources, parameters and response fields are made available to all versions.

You can request a specific version of the API parameters and responses by using the full version in the path, instead of “2”. For example, to access the original API 2 release, you can use a URL of http://CALENDAR-URL/api/2.0/.

Using http://CALENDAR-URL/api/2/ will give you the current version. When a new version of the API is launched, this endpoint will continue to serve the prior version for a short period of time, allowing time for clients to update.

The changes in each revision can be found in the recent changes section and are also documented with the associated resources.

Usage Limits

There are currently no defined usage limits on the API. However, be considerate when using the API and do not rapidly issue many requests, as well as caching data when possible (especially for less-frequently updated resources). We reserve the right to block offending hosts and/or applications to preserve the performance and stability of Localist.

All requests should either be OAuth signed or include identifying information in the User Agent.

Authentication

The Localist API is currently read-only; our authentication methods are under private testing.

API Terms of Use

Certain terms which are capitalized herein and not otherwise defined, have the meaning set forth in the Localist Terms of Service.

Your subscription to the Service enables you to access and use the API, including to develop and implement web and software services, scripts and applications (“Localist Applications”) for use in connection with your subscription to the Service for your internal business purposes in accordance with the Localist Terms of Service. Localist also permits you to publish Localist Applications and make them available to third parties subject to you entering into and complying with the Localist Application Developer and API Agreement.

In order to use and access the API, you must be an active Localist Enterprise Licensee. Your agreement is the only means through which you are authorized to access the API.

Except as expressly permitted pursuant to a Localist Application Developer and API Agreement to which you are a party to, you may not use or access the API to obtain access to or extract any data stored or transmitted through the Service other than Your Content or to input data from any external source into the Service other than to your Account.

You may not use the API to substantially replicate products or services offered by Localist, including, without limitation, functions or clients on platforms (such as iOS or Android) where Localist offers its own client or function. Localist Applications may not use or access the API or the Service in order to monitor the availability, performance, or functionality of any of the API or Service or for any similar benchmarking purposes.

You may not, under any circumstances, through a Localist Application or otherwise, repackage or resell the Service or API. You are not permitted to use or access the API in any manner that does or could potentially undermine the security of the Service, the API or any data or information stored or transmitted using the Service.

You may not (i) interfere with, modify or disable any features, functionality or security controls of the Service or the API: (ii) defeat, avoid, bypass, remove, deactivate or otherwise circumvent any protection mechanisms for the Service or the API; or (iii) reverse engineer, decompile, disassemble or derive source code, underlying ideas, algorithms, structure or organizational form from the Service or the API.

You are solely responsible (and Localist has no responsibility or liability of any kind), for the content, development, operation, or maintenance of Localist Applications. Without limiting the foregoing, you will be solely responsible for (i) the technical installation and operation of your Localist Applications; (ii) creating and displaying information and content on, through or within your Localist Applications; (iii) ensuring that your Localist Applications do not violate or infringe the Intellectual Property Rights of any third party; and (iv) ensuring that your Localist Applications do not contain or introduce Malicious Software into the Service, the API, or any data stored or transmitted using the Service.

You must respect and comply with the technical and policy-implemented limitations of the API and the restrictions Localist designs or informs you of in accessing or using the API or designing and implementing Localist Applications. Without limiting the foregoing, you may not violate any explicit rate limitations on calling or otherwise utilizing the API.

To the extent you develop or implement Localist Applications that transmit or otherwise use or access the API to transmit Your Content outside the Service, you will be responsible for any required notification to or consent of Agents or End Users that their data will be transmitted outside the Service. Localist is not responsible for the privacy, security or integrity of Your Content to the extent it is transmitted outside the Service by you or your Localist Applications using the API.

Recent Changes

October 8, 2013

Released API version 2.1.

July 2, 2013
June 20, 2013
May 8, 2013
May 7, 2013
May 1, 2013
October 1, 2012
September 27, 2012
July 16, 2012

Basic Concepts

Response Format

All responses are in JSON format. When representing an object, it is formatted as a hash with one element, with the key of the object type, and the value being a hash of the attributes of the object. For example, a event is represented like this:

{
  "event": {
    "id": 1,
    "name": "My Event",
    // other attributes
  }
}

Fields with a missing or blank value are not gauranteed to be present in the response. Your code should handle this situation, as the inclusion of empty fields in the response may change at any time.

Response Codes

The success or failure of the request is indicated using the HTTP status codes. In general, a 2xx code indicates success, while a 4xx code indicates failure.

Code Description
200 Response succeded
400 Error handling request
401 Authentication error
403 Forbidden
404 Not found
500 Internal Localist error

Response Errors

Error responses (4xx status codes) contain an error hash in the body with the error message and code. For example:

{
  "status": "error",
  "request": "/api/2/events/123",
  "error": "Not Found: Couldn't find Event with id=123",
  "code": "not_found"
}

The error attribute contains an error message. The code attribute contains a string indicating the type of error:

Code Description
access_denied This resource is not visible to the current user
argument_error An option provided contains an invalid format or value
authentication_required A valid access token is required to complete the request
not_found The resource requested does not exist
required_argument_missing A required option was not specified

Note: Responses with codes 403, 404 and 500 may return a HTML body instead of JSON. Your client should be prepared to handle this.

Geo Info

Contains structured geographic information, usually representing a specific point. Any or all of these elements may be missing if the address was not recognized.

{
  "city": "Ithaca",
  "country": "US",
  "latitude": 42.4425,
  "longitude": -76.4857,
  "state": "NY",
  "street": "430 College Ave",
  "zip": "14850"
}
Attribute Description
city City portion of address
country Country portion of address
latitude Latitude of address
longitude Longitude of address
state State portion of address
street Street portion of address
zip Postal code of address

Paging

Contains information about result set paging, including the total number of pages. Page numbers start at 1.

{
  "current": 1,
  "size": 10,
  "total": 1
}
Attribute Description
current Page number of the returned results
size Number of results per page
total Total number of pages

Filters

Represents the assigned filter items on an object.

An object can have multiple filter types (such as “Event Type” or “Department”), each of which can have multiple filter items assigned.

You can use the appropriate labels method on a resource to retrieve the displayed names of the filter types and custom fields.

The hash’s keys represent the filter types that are assigned, with the value being an array of the assigned filters.

{
  "departments": [
    {
      "id": 4859,
      "name": "School of Continuing Education and Summer Sessions"
    }
  ],
  "event_types": [
    {
      "id": 4262,
      "name": "Music"
    }
  ]
}
Attribute Description
id ID of the filter item, used with the type parameter when requesting resource listings
name The label of the filter item

Recent Activity

Recent activity covers three types of objects representing the content that can be posted by a user: comments, reviews, and photos. Not all types are available on all objects.

The recent activity result is a mixed array of the three types.

In addition, there are two common result attributes among the responses, user and on.

User

Contains information about the user who posted the item.

{
  "id": 12345,
  "photo_url": "http://images.localist.com/images/main/person_huge.png",
  "profile_url": "http://example.localist.com/johndoe",
  "visible_name": "John Doe"
}
Attribute Description
id The user’s ID
photo_url URL to the user’s profile photo
profile_url URL to the user’s profile page on Localist
visible_name The name of the user, suitable for display
On

Identifies what object the review or comment was posted to. Since a photo can be associated with multiple objects, it does not contain this information.

{
  "id": 73502,
  "type": "event"
}
Attribute Description
id The ID of the object
type The type of the object (event, photo, business or user)
Comment

Represents a comment posted by a user.

{
  "comment": {
    "body": "Will this event be live on the Web?",
    "created_at": "2012-04-19T13:35:50Z",
    "id": 1422,
    "on": {
      "id": 73502,
      "type": "event"
    },
    "updated_at": "2012-04-19T13:35:50Z",
    "user": {
      "id": 12345,
      "photo_url": "http://images.localist.com/images/main/person_huge.png",
      "profile_url": "http://example.localist.com/johndoe",
      "visible_name": "John Doe"
    },
    "when": "2012-04-19T09:35:50Z"
  }
}
Attribute Description
body The comment text
id ID of the comment
on Object the comment was posted on
user User who posted the comment
when Timestamp when the comment was posted
Review

Represents a review posted by a user. Identical to a comment with the addition of the rating key.

{
  "review": {
    "body": "It was great fun to see Venus directly in front of the sun.",
    "created_at": "2012-06-06T18:50:25Z",
    "id": 1443,
    "on": {
      "id": 76119,
      "type": "event"
    },
    "rating": 1,
    "updated_at": "2012-06-06T18:50:25Z",
    "user": {
      "id": 12345,
      "photo_url": "http://images.localist.com/images/main/person_huge.png",
      "profile_url": "http://example.localist.com/johndoe",
      "visible_name": "John Doe"
    },
    "when": "2012-06-05T00:00:00Z"
  }
}
Attribute Description
body The review text
id ID of the review
on Object the review was posted on
rating The user’s rating: -1 for a negative review, 0 for a neutral review, or 1 for a positive review
user User who posted the review
when Timestamp when the review was posted
Photo

Represents a photo entry in a recent activity list.

Since a photo can be associated with multiple objects, the on data is not provided.

Note: This is a slightly different format than the photo resource returns, as it includes more context for a recent activity listing.

{
  "photo": {
    "caption": "",
    "id": 626,
    "photo_url": "http://images.localist.com/photo/000/000/626/huge/jSNHHDAb_6Yp1_Li.jpg?1339699432",
    "updated_at": "2012-06-14T18:43:52Z",
    "user": {
      "photo_url": "http://images.localist.com/images/main/person_huge.png",
      "profile_url": "http://example.localist.com/johndoe",
      "visible_name": "John Doe"
    },
    "when": "2012-06-14T18:43:52Z"
  }
}
Attribute Description
caption The photo caption
id The photo’s ID
photo_url URL to the photo’s image
user User who posted the photo
when Timestamp when the photo was posted

Resources

Describes the available resources, their response formats, and associated methods. Variables in resource URLs are listed in all capital letters.

Note: All output samples have been reformatted for clarity, and some responses and values have been truncated.

Organizations

An organization is the root level that all content is attached to. A calendar always has one organization.

Format
{
  "organization": {
    "id": 55,
    "name": "WTMD",
    "urlname": "wtmd",
    "description": null,
    "time_zone": "Eastern Time (US & Canada)",
    "photo_id": null,
    "localist_url": "http://events.wtmd.org/",
    "photo_url": "http://images-cf.localist.com/images/main/person_huge.png"
  }
}
Attribute Description
description The organization’s description
id The organization’s ID (this is referenced as school_id in other resources)
localist_url URL to the organization’s page on Localist
name The organization’s name
photo_id ID of the organization’s photo, if set
photo_url URL to the organization’s photo
time_zone The organization’s time zone
urlname The organization’s URL slug
List

Resource: GET /organizations

Returns a paged listing of organizations on this calendar.

Parameter Type Description Default
page number Page number, starting from 1 1
pp number Number of items per page (max 100) 10

Example Request: GET http://CALENDAR-URL/api/2/organizations

{
  "organizations": [
    {
      "organization": {
        "id": 55,
        "name": "WTMD",
        "urlname": "wtmd",
        "description": null,
        "time_zone": "Eastern Time (US & Canada)",
        "photo_id": null,
        "localist_url": "http://events.wtmd.org/",
        "photo_url": "http://images-cf.localist.com/images/main/person_huge.png"
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 1
  }
}
Get

Resource: GET /organizations/ORGANIZATION_ID

Retrieve details about one organization.

Example Request: GET http://CALENDAR-URL/api/2/organizations/55

{
  "organization": {
    "id": 55,
    "name": "WTMD",
    "urlname": "wtmd",
    "description": null,
    "time_zone": "Eastern Time (US & Canada)",
    "photo_id": null,
    "localist_url": "http://events.wtmd.org/",
    "photo_url": "http://images-cf.localist.com/images/main/person_huge.png"
  }
}
Communities List

Resource: GET /organizations/ORGANIZATION_ID/communities

Returns a paged listing of the communities associated with this organization.

Example Request: GET http://CALENDAR-URL/api/2/organziations/11/communities

{
  "communities": [
    {
      "community": {
        "id": 62,
        "name": "Sacramento",
        "urlname": "sacramento",
        "description": "",
        "time_zone": "Pacific Time (US & Canada)",
        "photo_id": null,
        "school_id": 11,
        "localist_url": "https://calendar.pacific.edu/sacramento",
        "photo_url": "https://d3e1o4bcbhmj8g.cloudfront.net/images/main/person_hug..."
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 1
  }
}

Communities

A community represents a separate location within an organization, such as a college campus, association chapter, or regional market.

Format
{
  "community": {
    "id": 62,
    "name": "Sacramento",
    "urlname": "sacramento",
    "description": "",
    "time_zone": "Pacific Time (US & Canada)",
    "photo_id": null,
    "school_id": 11,
    "localist_url": "https://calendar.pacific.edu/sacramento",
    "photo_url": "https://d3e1o4bcbhmj8g.cloudfront.net/images/main/person_hug..."
  }
}
Attribute Description
description The community’s description
id The community’s ID (this is referenced as campus_id in other resources)
localist_url URL to the community’s page on Localist
name The community’s name
photo_id ID of the community’s photo, if set
photo_url URL to the community’s photo
school_id The organization this community belongs to
time_zone The community’s time zone
urlname The community’s URL slug
List

Resource: GET /organizations/ORGANIZATION_ID/communities

Returns a paged listing of communities in the specified organization.

Parameter Type Description Default
page number Page number, starting from 1 1
pp number Number of items per page (max 100) 10

Example Request: GET http://CALENDAR-URL/api/2/organizations/11/communities

{
  "communities": [
    {
      "community": {
        "id": 62,
        "name": "Sacramento",
        "urlname": "sacramento",
        "description": "",
        "time_zone": "Pacific Time (US & Canada)",
        "photo_id": null,
        "school_id": 11,
        "localist_url": "https://calendar.pacific.edu/sacramento",
        "photo_url": "https://d3e1o4bcbhmj8g.cloudfront.net/images/main/person_hug..."
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 1
  }
}
Get

Resource: GET /organizations/ORGANIZATION_ID/communities/COMMUNITY_ID

Retrieve details about one community.

Example Request: GET http://CALENDAR-URL/api/2/organizations/11/community/62

{
  "community": {
    "id": 62,
    "name": "Sacramento",
    "urlname": "sacramento",
    "description": "",
    "time_zone": "Pacific Time (US & Canada)",
    "photo_id": null,
    "school_id": 11,
    "localist_url": "https://calendar.pacific.edu/sacramento",
    "photo_url": "https://d3e1o4bcbhmj8g.cloudfront.net/images/main/person_hug..."
  }
}

Events

These resources provide access to information about events.

Format
{
  "event": {
    "id": 188155,
    "title": "Amy Sherald: Paintings",
    "url": "http://www.rflewismuseum.org/exhibitions/special",
    "updated_at": "2013-10-08T09:25:32Z",
    "created_at": "2013-08-26T06:26:44Z",
    "facebook_id": null,
    "first_date": "2013-09-14",
    "last_date": "2013-12-29",
    "hashtag": "",
    "urlname": "amy_sherald_paintings",
    "user_id": 52182,
    "directions": "",
    "allows_reviews": true,
    "location": "Reginald F. Lewis of Maryland African American History and C...",
    "room_number": "",
    "location_name": "Reginald F. Lewis of Maryland African American History and C...",
    "created_by": null,
    "updated_by": null,
    "city_id": 1,
    "neighborhood_id": 58,
    "school_id": 55,
    "campus_id": null,
    "recurring": true,
    "free": true,
    "private": false,
    "verified": true,
    "rejected": false,
    "sponsored": false,
    "venue_id": null,
    "ticket_url": "",
    "ticket_cost": "",
    "keywords": [

    ],
    "tags": [

    ],
    "description_text": "Known for her life-sized fantastical portraits of African Am...",
    "photo_id": 76525,
    "detail_views": 52,
    "address": "830 E. Pratt St. Baltimore, MD 21202",
    "description": "<p class=\"description\">Known for her life-sized fantastical ...",
    "featured": true,
    "geo": {
      "latitude": 39.2873,
      "longitude": -76.6038,
      "street": "830 East Pratt Street",
      "city": "Baltimore",
      "state": "MD",
      "country": "US",
      "zip": "21202"
    },
    "filters": {
      "event_types": [
        {
          "name": "Arts & Culture",
          "id": 20196
        }
      ]
    },
    "custom_fields": {
    },
    "localist_url": "http://events.wtmd.org/event/amy_sherald_paintings",
    "photo_url": "http://images-cf.localist.com/photos/76525/huge/195a2ae18388...",
    "venue_url": null,
    "event_instances": [
      {
        "event_instance": {
          "id": 452831,
          "ranking": 0,
          "event_id": 188155,
          "start": "2013-09-14T10:00:00-04:00",
          "end": "2013-09-14T17:00:00-04:00",
          "all_day": false
        }
      }
    ]
  }
}
Attribute Description
address The address of the event
allows_reviews true if reviews are enabled on this event, false otherwise
attendees Array of the event’s attendees
campus_id The community the event is assigned to
created_at Timestamp of the event’s creation
created_by ID of the user who initially submitted this event, or null if added through an external feed or CSV
custom_fields Hash of custom fields set on the event. The key is the “unique identifier” of the field, with the value being the field’s value.
department_id What department group this event belongs to (for calendars with advanced department functionality only)
department_name Name of the department group represented by department_id (for calendars with advanced department functionality only)
description_text Plain-text version of the event’s description since v2.1
description The event’s description, including HTML since v2.1
description The event’s plain-text description before v2.1
directions Directions to the event’s location
event_instances Array of instances for this event
facebook_id ID of associated event on Facebook
featured true if the event is featured, false otherwise
filters Hash of filters set on the event. The key is the filter’s identifier, the value is an array of filter items for each assigned value.
first_date The date of the earliest instance
free true if the event is free
geo Hash of geographical information
group_id ID of group assigned to the event
group_name Name of group assigned to the event
hashtag The event’s hashtag
id ID of the event (used as event_id in other resources)
keywords Array of keywords assigned to the event
last_date The date of the latest instance
localist_url URL to the event’s page on Localist
location_name Appropriate label for showing the location (either the place name or the location field)
location Custom location assigned to the event (will be blank if a place is assigned)
photo_id ID of the assigned photo
photo_url URL of the assigned photo
private always false
recurring true if the event is recurring (has more than 5 instances)
rejected true if the event has been rejected
room_number Room number
school_id The organization this event is assigned to
sponsored true if the event is marked as sponsored
tags Array of tags assigned to the event
ticket_cost Ticket cost
ticket_url Ticket URL
title Name of the event
updated_at Timestamp of the event’s last update (does not necessarily indicate updates to the event’s visible details)
updated_by ID of the last user to edit the event (may be null, does not necessarily indicate updates to the event’s visible details)
url External URL assigned to the event
urlname URL slug of the event (used in URLs)
user_id ID of the event’s owner. May be null and does not necessarily represent the submitter.
venue_id ID of the associated place
venue_url URL of the place’s page on Localist
verified true if the event is verified
Event Instance Format

Represents information about one specific instance of an event. The attendance and num_attending attributes may not be present.

{
  "event_instance": {
    "attending": "none",
    "num_attending": 0,
    "id": 237631,
    "ranking": 0,
    "event_id": 81300,
    "start": "2013-09-14T21:00:00-04:00",
    "end": null,
    "all_day": false
  }
}
Attribute Description
all_day true if the event is all day (has no start time)
attending The current user’s attendance status (attending, watching, or none)
end Timestamp of the instance’s end, or null if not specified
event_id ID of event this instance belongs to
id ID of this event instance
num_attending Number of attendees
ranking Relative ranking of the event instance’s popularity, from 0-100
start Timestamp of the instance start

Note: The start timestamp always includes a time, even if none was specified on the event. The all_day flag will be true if there is no defined start time.

List

Resource: GET /events

Returns a paged list of events. By default, includes all events available on a calendar, but can be limited using the locality parameters.

The events can be further limited based on date or assigned filters.

The result hash includes an array of event objects in the events key, a date key describing the date range returned, and a page key with paging information.

Locality Parameters

These parameters restrict the results based on location.

Parameter Type Description Default
bounds string Return events within this bounding box
The bounding box is specified as: swlat,swlng,nelat,nelng
 
campus_id number The community to return events for all communities
group_id number The group or department group to return events for all
near string The latitude and longitude, separated by commas, to search near  
units string Units (mi or km) to use with within mi
venue_id number The place to return events for all places
within number Return events within this many units of near 10
Date Parameters

Control the range of events to return.

All dates should be specified as YYYY-MM-DD (2013-09-20). The maximum date range supported is 365 days. Longer ranges will be truncated to 365 days from start.

Parameter Type Description Default
days number Return events within this many days after start
Cannot be used with end
1
end date End of range today
start date Start of range today
Page Parameters

Specifies the size and offset of the results.

Parameter Type Description Default
page number Page number of results to return, starting with 1 1
pp number Number of events to return per page (1-100) 10
Filter Parameters

Restrict the returned events based on filter items, tags and keywords assigned.

To specify multiple values for type, keyword or exclude_type, the parameter may be repeated with brackets ([]) after the name.

For instance, to request both keyword kw1 and kw2, use a URL similar to: http://CALENDAR-URL/api/2/events?keyword[]=kw1&keyword[]=kw2.

Parameter Type Description Default
created_after date Only return places created after this date  
created_before date Only return places created before this date  
exclude_type number Do not return events with these filter item IDs  
featured boolean Only return featured events when true false
keyword string Limit to events with specified keywords or tags  
match string Control matching requirements for type and keyword
When not specified, matches events that have at least one listed type and one listed keyword
When all, matches events that have all the listed types and keywords
When any, matches events that have at least one of the listed types or keywords
 
require_all boolean deprecated, acts as match=all when true false
sponsored boolean Only return places marked as sponsored if true false
type number Limit events to filter item IDs  
Output Parameters

Note: Sorting by distance is only supported when near is specified.

Parameter Type Description Default
all_custom_fields boolean Include all custom fields in the result when true.
By default, only fields visible on the event detail page are returned.
false
direction string Change sort order, asc or desc varies
distinct boolean Only return the first matching instance of an event when true false
include_attendance boolean Include user’s attendance status in the result
Must be an authenticated request
false
sort string Sort results by
date: event start
name: event name
ranking: event popularity
distance: distance from near
created: event creation timestamp
updated: event update timestamp
date

Example Request: GET http://CALENDAR-URL/api/2/events

{
  "events": [
    {
      "event": {
        "event_instances": [
          {
            "event_instance": {
              "id": 452848,
              "ranking": 0,
              "event_id": 188155,
              "start": "2013-10-09T10:00:00-04:00",
              "end": "2013-10-09T17:00:00-04:00",
              "all_day": false
            }
          }
        ],
        "id": 188155,
        "title": "Amy Sherald: Paintings",
        "url": "http://www.rflewismuseum.org/exhibitions/special",
        "updated_at": "2013-10-08T09:25:32Z",
        "created_at": "2013-08-26T06:26:44Z",
        "facebook_id": null,
        "first_date": "2013-09-14",
        "last_date": "2013-12-29",
        "hashtag": "",
        "urlname": "amy_sherald_paintings",
        "user_id": 52182,
        "directions": "",
        "allows_reviews": true,
        "location": "Reginald F. Lewis of Maryland African American History and C...",
        "room_number": "",
        "location_name": "Reginald F. Lewis of Maryland African American History and C...",
        "created_by": null,
        "updated_by": null,
        "city_id": 1,
        "neighborhood_id": 58,
        "school_id": 55,
        "campus_id": null,
        "recurring": true,
        "free": true,
        "private": false,
        "verified": true,
        "rejected": false,
        "sponsored": false,
        "venue_id": null,
        "ticket_url": "",
        "ticket_cost": "",
        "keywords": [

        ],
        "tags": [

        ],
        "description_text": "Known for her life-sized fantastical portraits of African Am...",
        "photo_id": 76525,
        "detail_views": 52,
        "address": "830 E. Pratt St. Baltimore, MD 21202",
        "description": "<p class=\"description\">Known for her life-sized fantastical ...",
        "featured": true,
        "geo": {
          "latitude": 39.2873,
          "longitude": -76.6038,
          "street": "830 East Pratt Street",
          "city": "Baltimore",
          "state": "MD",
          "country": "US",
          "zip": "21202"
        },
        "filters": {
          "event_types": [
            {
              "name": "Arts & Culture",
              "id": 20196
            }
          ]
        },
        "custom_fields": {
        },
        "localist_url": "http://events.wtmd.org/event/amy_sherald_paintings",
        "photo_url": "http://images-cf.localist.com/photos/76525/huge/195a2ae18388...",
        "venue_url": null
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 10
  },
  "date": {
    "first": "2013-10-08",
    "last": "2013-11-07"
  }
}

Resource: GET /events/search

Searches for events with the search term specified in search.

Supports all parameters supported by event list, except for keyword, match, created_before, created_after. Keywords and tags are searched as part of search.

Sorting by created and updated is not supported.

Parameter Type Description Default
search string required search terms  

The response format is the same as for event list.

Example Request: GET http://CALENDAR-URL/api/2/events/search?search=concert

{
  "events": [
    {
      "event": {
        "event_instances": [
          {
            "event_instance": {
              "id": 452848,
              "ranking": 0,
              "event_id": 188155,
              "start": "2013-10-09T10:00:00-04:00",
              "end": "2013-10-09T17:00:00-04:00",
              "all_day": false
            }
          }
        ],
        "id": 188155,
        "title": "Amy Sherald: Paintings",
        "url": "http://www.rflewismuseum.org/exhibitions/special",
        "updated_at": "2013-10-08T09:25:32Z",
        "created_at": "2013-08-26T06:26:44Z",
        "facebook_id": null,
        "first_date": "2013-09-14",
        "last_date": "2013-12-29",
        "hashtag": "",
        "urlname": "amy_sherald_paintings",
        "user_id": 52182,
        "directions": "",
        "allows_reviews": true,
        "location": "Reginald F. Lewis of Maryland African American History and C...",
        "room_number": "",
        "location_name": "Reginald F. Lewis of Maryland African American History and C...",
        "created_by": null,
        "updated_by": null,
        "city_id": 1,
        "neighborhood_id": 58,
        "school_id": 55,
        "campus_id": null,
        "recurring": true,
        "free": true,
        "private": false,
        "verified": true,
        "rejected": false,
        "sponsored": false,
        "venue_id": null,
        "ticket_url": "",
        "ticket_cost": "",
        "keywords": [

        ],
        "tags": [

        ],
        "description_text": "Known for her life-sized fantastical portraits of African Am...",
        "photo_id": 76525,
        "detail_views": 52,
        "address": "830 E. Pratt St. Baltimore, MD 21202",
        "description": "<p class=\"description\">Known for her life-sized fantastical ...",
        "featured": true,
        "geo": {
          "latitude": 39.2873,
          "longitude": -76.6038,
          "street": "830 East Pratt Street",
          "city": "Baltimore",
          "state": "MD",
          "country": "US",
          "zip": "21202"
        },
        "filters": {
          "event_types": [
            {
              "name": "Arts & Culture",
              "id": 20196
            }
          ]
        },
        "custom_fields": {
        },
        "localist_url": "http://events.wtmd.org/event/amy_sherald_paintings",
        "photo_url": "http://images-cf.localist.com/photos/76525/huge/195a2ae18388...",
        "venue_url": null
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 10
  },
  "date": {
    "first": "2013-10-08",
    "last": "2013-11-07"
  }
}
Get

Resource: GET /events/EVENT_ID

Returns details about the event specified by event_id.

If requested, attendees will be included in an attendees attribute, recent activity will be in an recent_activity attribute and attendance info will be on the event instance.

Parameter Type Description Default
all_custom_fields boolean Include all custom fields in the result when true.
By default, only fields visible on the event detail page are returned.
false
include_activity boolean Include recent activity feed false
include_attendance boolean Include user’s attendance status in the result
Must be an authenticated request
false
include_attendees boolean Include attendee list in the result false

Example Request: GET http://CALENDAR-URL/api/2/events/188155

{
  "event": {
    "id": 188155,
    "title": "Amy Sherald: Paintings",
    "url": "http://www.rflewismuseum.org/exhibitions/special",
    "updated_at": "2013-10-08T09:25:32Z",
    "created_at": "2013-08-26T06:26:44Z",
    "facebook_id": null,
    "first_date": "2013-09-14",
    "last_date": "2013-12-29",
    "hashtag": "",
    "urlname": "amy_sherald_paintings",
    "user_id": 52182,
    "directions": "",
    "allows_reviews": true,
    "location": "Reginald F. Lewis of Maryland African American History and C...",
    "room_number": "",
    "location_name": "Reginald F. Lewis of Maryland African American History and C...",
    "created_by": null,
    "updated_by": null,
    "city_id": 1,
    "neighborhood_id": 58,
    "school_id": 55,
    "campus_id": null,
    "recurring": true,
    "free": true,
    "private": false,
    "verified": true,
    "rejected": false,
    "sponsored": false,
    "venue_id": null,
    "ticket_url": "",
    "ticket_cost": "",
    "keywords": [

    ],
    "tags": [

    ],
    "description_text": "Known for her life-sized fantastical portraits of African Am...",
    "photo_id": 76525,
    "detail_views": 52,
    "address": "830 E. Pratt St. Baltimore, MD 21202",
    "description": "<p class=\"description\">Known for her life-sized fantastical ...",
    "featured": true,
    "geo": {
      "latitude": 39.2873,
      "longitude": -76.6038,
      "street": "830 East Pratt Street",
      "city": "Baltimore",
      "state": "MD",
      "country": "US",
      "zip": "21202"
    },
    "filters": {
      "event_types": [
        {
          "name": "Arts & Culture",
          "id": 20196
        }
      ]
    },
    "custom_fields": {
    },
    "localist_url": "http://events.wtmd.org/event/amy_sherald_paintings",
    "photo_url": "http://images-cf.localist.com/photos/76525/huge/195a2ae18388...",
    "venue_url": null,
    "event_instances": [
      {
        "event_instance": {
          "id": 452831,
          "ranking": 0,
          "event_id": 188155,
          "start": "2013-09-14T10:00:00-04:00",
          "end": "2013-09-14T17:00:00-04:00",
          "all_day": false
        }
      }
    ]
  }
}
Recent Activity

Resource: GET /events/EVENT_ID/activity

Returns a paged result set of recent activity on the event specified by event_id.

The activity key in the result is an array of activity items. The page key contains paging details.

Parameter Type Description Default
page number Page number of results to return, starting with 1 1
pp number Number of events to return per page (1-100) 10

Example Request: GET http://CALENDAR-URL/api/2/events/81300/activity

{
  "activity": [
    {
      "photo": {
        "caption": "",
        "id": 219,
        "photo_url": "http://images-cf.localist.com/photos/219/huge/bc33c6375295e5f1c324b3826d201c548ff52c39.jpg?1379709611",
        "updated_at": "2013-09-20T20:40:11Z",
        "user": {
          "id": 1,
          "photo_url": "http://images-cf.localist.com/photos/189/huge/fbe183f9caa62d281653b5a764e5f6e8fc1afe5f.jpg?1376942064",
          "profile_url": "http://example.localist.com/eric",
          "visible_name": "Eric"
        },
        "when": "2013-09-20T20:40:11Z"
      }
    },
    {
      "review": {
        "body": "awesome",
        "created_at": "2013-09-20T20:40:01Z",
        "id": 1473,
        "on": {
          "id": 81300,
          "type": "event"
        },
        "rating": 1,
        "updated_at": "2013-09-20T20:40:01Z",
        "user": {
          "id": 1,
          "photo_url": "http://images-cf.localist.com/photos/189/huge/fbe183f9caa62d281653b5a764e5f6e8fc1afe5f.jpg?1376942064",
          "profile_url": "http://example.localist.com/eric",
          "visible_name": "Eric"
        },
        "when": "2013-09-20T20:40:01Z"
      }
    },
    {
      "comment": {
        "body": "my comment",
        "created_at": "2013-09-20T20:39:54Z",
        "id": 1470,
        "on": {
          "id": 81300,
          "type": "event"
        },
        "updated_at": "2013-09-20T20:39:54Z",
        "user": {
          "id": 1,
          "photo_url": "http://images-cf.localist.com/photos/189/huge/fbe183f9caa62d281653b5a764e5f6e8fc1afe5f.jpg?1376942064",
          "profile_url": "http://example.localist.com/eric",
          "visible_name": "Eric"
        },
        "when": "2013-09-20T16:39:54Z"
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 1
  }
}
Attendees

Resource: GET /events/EVENT_ID/attendees

Returns the attendees on the event specified by event_id.

The attendees key will contain an array of user objects. Note that the user key for the object may also be external_attendee or private_user.

Attendees from external sources (such as Facebook) are represented by external_attendee. The localist_url attribute provides the best possible profile page, but may be absent. The id is unique to external attendees.

A user with privacy settings preventing details from being shown is represented by a private_user. id and localist_url are null in this case.

Example Request: GET http://CALENDAR-URL/api/2/events/81300/attendees

{
  "attendees": [
    {
      "user": {
        "id": 1,
        "localist_url": "http://example.localist.com/eric",
        "photo_url": "http://images-cf.localist.com/photos/189/huge/fbe183f9caa62d281653b5a764e5f6e8fc1afe5f.jpg?1376942064",
        "visible_name": "Eric"
      }
    },
    {
      "external_attendee": {
        "id": 297248,
        "localist_url": "http://www.facebook.com/111111111",
        "photo_url": "http://images-cf.localist.com/images/main/person_huge.png",
        "visible_name": "John Doe"
      }
    },
    {
      "private_user": {
        "id": null,
        "localist_url": null,
        "photo_url": "http://images-cf.localist.com/images/main/person_huge.png",
        "visible_name": "Private"
      }
    }
  ]
}
Attendance

Gets or modifies the user’s attendance status on the event. All attendance methods require a valid access token.

Get Attendance

Resource: GET /events/EVENT_ID/attendance

Requires authentication.

To retrieve attendance, perform a HTTP GET on this resource.

Returns a list of event instances the user is attending in the attendances key.

Example Request: GET http://CALENDAR-URL/api/2/events/81300/attendance

{
  "attendances": [
    {
      "event_instance": {
        "attending": "attending",
        "num_attending": 3,
        "id": 237632,
        "ranking": 0,
        "event_id": 81300,
        "start": "2013-09-20T21:00:00-04:00",
        "end": null,
        "all_day": false
      }
    }
  ]
}
Add Attendance

Resource: POST /events/EVENT_ID/attendance

Requires authentication.

To add attendance on an event, perform a HTTP POST on this resource, with either the event_instances_id or dates parameter. Both accept multiple values with array syntax (event_instances_id[] or dates[]). The parameters may be in either the URL or as the form data.

Parameter Type Description Default
dates date Dates (YYYY-MM-DD) of instances to add attendance  
event_instances_id number ID(s) of event instances to add attendance  

Example Request: POST http://CALENDAR-URL/api/2/events/81300/attendance?dates=2013-09-20

{
  "status": "success"
}
Remove Attendance

Resource: DELETE /events/EVENT_ID/attendance

Requires authentication.

To add attendance on an event, perform a HTTP DELETE on this resource, with either the event_instances_id or dates parameter. Both accept multiple values with array syntax (event_instances_id[] or dates[]). The parameters may be in either the URL or as the form data.

Parameter Type Description Default
dates date Dates (YYYY-MM-DD) of instances to add attendance  
event_instances_id number ID(s) of event instances to add attendance  

Example Request: DELETE http://CALENDAR-URL/api/2/events/81300/attendance?dates=2013-09-20

{
  "status": "success"
}
Filters

Resource: GET /events/filters

Returns the list of event filter items. The ID can be used in the type parameter to /events.

The parent_id attribute represents the parent filter item, if a child filter.

Example Request: GET http://CALENDAR-URL/api/2/events/filters

{
  "event_types": [
    {
      "id": 20050,
      "name": "Music",
      "parent_id": null
    }
  ],
  "departments": [
    {
      "id": 20860,
      "name": "WTMD Welcomes",
      "parent_id": null
    }
  ]
}
Labels

Resource: GET /events/labels

Returns the display labels for filter types and custom fields. The key is the identifier (as used in other responses) and value is the user-friendly label.

Example Request: GET http://CALENDAR-URL/api/2/events/labels

{
  "custom_fields": {
  },
  "filters": {
    "event_types": "Event Types",
    "departments": "Departments"
  }
}

Places

This resource provides access to place data.

Format
{
  "place": {
    "id": 66194,
    "name": "1st Mariner Arena",
    "type": "Business",
    "neighborhood_id": 4,
    "city_id": "1",
    "campus_id": null,
    "school_id": 55,
    "created_at": "2013-04-05T18:02:52Z",
    "updated_at": "2013-04-22T17:07:32Z",
    "time_zone": "Eastern Time (US & Canada)",
    "photo_id": 60978,
    "ranking": 0,
    "twitter_name": null,
    "facebook_id": null,
    "foursquare_id": null,
    "urlname": "1stmarinerarena",
    "verified": true,
    "tags": [

    ],
    "description_text": "1st Mariner Arena is City-owned facility which hosts an aver...",
    "description": "1st Mariner Arena is City-owned facility which hosts an aver...",
    "keywords": [

    ],
    "geo": {
      "latitude": 39.2885,
      "longitude": -76.6187,
      "street": "201 West Baltimore Street",
      "city": "Baltimore",
      "state": "MD",
      "country": "US",
      "zip": "21201"
    },
    "url": "",
    "directions": null,
    "phone": "",
    "hours": "",
    "parking": null,
    "sponsored": false,
    "address": "201 W Baltimore St, Baltimore, MD 21201, USA",
    "filters": {
    },
    "custom_fields": {
    },
    "localist_url": "http://events.wtmd.org/1stmarinerarena",
    "photo_url": "http://images-cf.localist.com/photos/60978/huge/0c21bfeaedf9..."
  }
}
Attribute Description
address Street address
campus_id ID of the community the place belongs to
city_id The ID of the place’s city
created_at Timestamp of the place’s creation
custom_fields Hash of custom fields set on the place. The key is the “unique identifier” of the field, with the value being the field’s value.
description_text Plain-text version of the place’s description since v2.1
description The place’s description, including HTML since v2.1
description The place’s plain-text description before v2.1
directions Directions
filters Hash of filters set on the place. The key is the filter’s identifier, the value is an array of filter items for each assigned value.
foursquare_id ID of a related Foursquare place
geo Geographical information
hours Hours of operation
id The place’s ID (used as venue_id or business_id in other resources)
keywords Array of keywords assigned to the place
localist_url URL to the place’s page on Localist
name The place’s name
parking Parking details
phone Phone number
photo_id ID of photo assigned to place
photo_url URL to the place’s photo
ranking Relative ranking of the place’s popularity (0-100)
school_id ID of the organization the place belongs to
sponsored true if the place is marked as sponsored
tags Array of tags assigned to the place
twitter_name The place’s twitter handle
updated_at Timestamp of the place’s last update (does not necessarily indicate changes to any details)
url Place’s web page URL
urlname URL slug of the place (used in URLs)
verified true if this place is verified
List

Resource: GET /places

Returns a paged list of places. By default, includes all places available on a calendar, but can be limited using the locality parameters.

The places can be further limited based on assigned filters.

The result hash includes an array of place objects in the places key, and a page key with paging information.

Locality Parameters

These parameters restrict the results based on location.

Parameter Type Description Default
bounds string Return places within this bounding box
The bounding box is specified as: swlat,swlng,nelat,nelng
 
campus_id number The community to return places for all communities
near string The latitude and longitude, separated by commas, to search near  
units string Units (mi or km) to use with within mi
within number Return places within this many units of near 10
Page Parameters

Specifies the size and offset of the results.

Parameter Type Description Default
page number Page number of results to return, starting with 1 1
pp number Number of places to return per page (1-100) 10
Filter Parameters

Restrict the returned places based on filter items, tags and keywords assigned.

To specify multiple values for type, keyword or exclude_type, the parameter may be repeated with brackets ([]) after the name.

For instance, to request both keyword kw1 and kw2, use a URL similar to: http://CALENDAR-URL/api/2/places?keyword[]=kw1&keyword[]=kw2.

Parameter Type Description Default
created_after date Only return places created after this date  
created_before date Only return places created before this date  
exclude_type number Do not return places with these filter item IDs  
keyword string Limit places with keywords or tags  
sponsored boolean Only return places marked as sponsored if true false
type number Limit places to filter item IDs  
Output Parameters

Note: Sorting by distance is only supported when near is specified.

Parameter Type Description Default
all_custom_fields boolean Include all custom fields in the result when true.
By default, only fields visible on the place’s detail page are returned.
false
direction string Change sort order, asc or desc varies
sort string Sort results by
name: place name
ranking: place popularity
distance: distance from near
created: timestamp of creation
updated: timestamp of last update
name

Example Request: GET http://CALENDAR-URL/api/2/places

{
  "places": [
    {
      "place": {
        "id": 66398,
        "name": "Abbey Burger Bistro",
        "type": "Business",
        "neighborhood_id": 3,
        "city_id": "1",
        "campus_id": null,
        "school_id": 55,
        "created_at": "2013-04-05T18:06:14Z",
        "updated_at": "2013-04-22T17:09:16Z",
        "time_zone": "Eastern Time (US & Canada)",
        "photo_id": 61177,
        "ranking": 0,
        "twitter_name": null,
        "facebook_id": null,
        "foursquare_id": null,
        "urlname": "abbeyburgerbistro",
        "verified": true,
        "tags": [

        ],
        "description_text": "In need of an upscale burger joint? Look no further than The...",
        "description": "In need of an upscale burger joint? Look no further than The...",
        "keywords": [

        ],
        "geo": {
          "latitude": 39.2772,
          "longitude": -76.6129,
          "street": "1041 Marshall Street",
          "city": "Baltimore",
          "state": "MD",
          "country": "US",
          "zip": "21230"
        },
        "url": "",
        "directions": null,
        "phone": "",
        "hours": "",
        "parking": null,
        "sponsored": false,
        "address": "1041 Marshall St, Baltimore, MD 21230, USA",
        "filters": {
        },
        "custom_fields": {
        },
        "localist_url": "http://events.wtmd.org/abbeyburgerbistro",
        "photo_url": "http://images-cf.localist.com/photos/61177/huge/5543d0ed043d..."
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 53
  }
}

Resource: GET /places/search

Searches for places with the search term specified in search.

Supports all parameters supported by place list, except for keyword, created_before, created_after. Keywords are searched as part of search.

Sorting by created and updated is not supported.

Parameter Type Description Default
search string required search terms  

The response format is the same as for place list.

Example Request: GET http://CALENDAR-URL/api/2/places/search?search=arena

{
  "places": [
    {
      "place": {
        "id": 66359,
        "name": "Arena Players",
        "type": "Business",
        "neighborhood_id": 5,
        "city_id": "1",
        "campus_id": null,
        "school_id": 55,
        "created_at": "2013-04-05T18:05:36Z",
        "updated_at": "2013-04-22T17:09:03Z",
        "time_zone": "Eastern Time (US & Canada)",
        "photo_id": 61139,
        "ranking": 0,
        "twitter_name": null,
        "facebook_id": null,
        "foursquare_id": null,
        "urlname": "arenaplayers",
        "verified": true,
        "tags": [

        ],
        "description_text": "Transcending the boundaries of race and ethnicity with each ...",
        "description": "Transcending the boundaries of race and ethnicity with each ...",
        "keywords": [

        ],
        "geo": {
          "latitude": 39.2988,
          "longitude": -76.6227,
          "street": "801 McCulloh Street",
          "city": "Baltimore",
          "state": "MD",
          "country": "US",
          "zip": "21201"
        },
        "url": "",
        "directions": null,
        "phone": "",
        "hours": "",
        "parking": null,
        "sponsored": false,
        "address": "801 McCulloh St, Baltimore, MD 21201, USA",
        "filters": {
        },
        "custom_fields": {
        },
        "localist_url": "http://events.wtmd.org/arenaplayers",
        "photo_url": "http://images-cf.localist.com/photos/61139/huge/e71c273317d7..."
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 1
  }
}
Get

Resource: GET /places/PLACE_ID

Returns details about the place specified by place_id.

Parameter Type Description Default
all_custom_fields boolean Include all custom fields in the result when true.
By default, only fields visible on the place’s detail page are returned.
false

Example Request: GET http://CALENDAR-URL/api/2/places/66194

{
  "place": {
    "id": 66194,
    "name": "1st Mariner Arena",
    "type": "Business",
    "neighborhood_id": 4,
    "city_id": "1",
    "campus_id": null,
    "school_id": 55,
    "created_at": "2013-04-05T18:02:52Z",
    "updated_at": "2013-04-22T17:07:32Z",
    "time_zone": "Eastern Time (US & Canada)",
    "photo_id": 60978,
    "ranking": 0,
    "twitter_name": null,
    "facebook_id": null,
    "foursquare_id": null,
    "urlname": "1stmarinerarena",
    "verified": true,
    "tags": [

    ],
    "description_text": "1st Mariner Arena is City-owned facility which hosts an aver...",
    "description": "1st Mariner Arena is City-owned facility which hosts an aver...",
    "keywords": [

    ],
    "geo": {
      "latitude": 39.2885,
      "longitude": -76.6187,
      "street": "201 West Baltimore Street",
      "city": "Baltimore",
      "state": "MD",
      "country": "US",
      "zip": "21201"
    },
    "url": "",
    "directions": null,
    "phone": "",
    "hours": "",
    "parking": null,
    "sponsored": false,
    "address": "201 W Baltimore St, Baltimore, MD 21201, USA",
    "filters": {
    },
    "custom_fields": {
    },
    "localist_url": "http://events.wtmd.org/1stmarinerarena",
    "photo_url": "http://images-cf.localist.com/photos/60978/huge/0c21bfeaedf9..."
  }
}
Filters

Resource: GET /places/filters

Returns the list of place filter items. The ID can be used in the type parameter to /places.

The parent_id attribute represents the parent filter item, if a child item.

Example Request: GET http://CALENDAR-URL/api/2/places/filters

{
  "business_type": [
    {
      "id": 2335,
      "name": "Bar",
      "parent_id": null
    }
  ]
}
Labels

Resource: GET /places/labels

Returns the display labels for filter types and custom fields. The key is the identifier (as used in other responses) and value is the user-friendly label.

Example Request: GET http://CALENDAR-URL/api/2/places/labels

{
  "custom_fields": {
  },
  "filters": {
    "business_type": "Place Types"
  }
}

Groups

This resource provides access to groups.

Format
{
  "group": {
    "id": 3948,
    "name": "CUWinds",
    "urlname": "cuwinds",
    "created_at": "2012-10-09T13:21:45Z",
    "updated_at": "2012-10-10T12:49:41Z",
    "photo_id": null,
    "school_id": 10,
    "campus_id": null,
    "url": "http://www.cuwinds.com/",
    "description_text": "CU WINDS unites Cornell University students who seek remarka...",
    "description": "CU WINDS unites Cornell University students who seek remarka...",
    "filters": {
    },
    "custom_fields": {
    },
    "localist_url": "http://events.cornell.edu/group/cuwinds",
    "photo_url": "http://images-cf.localist.com/images/main/business_huge.png?..."
  }
}
Attribute Description
campus_id ID of the community the group belongs to
created_at Timestamp of the group’s creation
custom_fields Hash of custom fields set on the group. The key is the “unique identifier” of the field, with the value being the field’s value.
description_text Plain-text version of the group’s description
description The group’s description, including HTML
filters Hash of filters set on the group. The key is the filter’s identifier, the value is an array of filter items for each assigned value.
id The group’s ID (used as group_id in other resources)
localist_url URL to the group’s page on Localist
name The group’s name
photo_id ID of photo assigned to group
photo_url URL to the group’s photo
school_id ID of the organization the group belongs to
tags Array of tags assigned to the group
updated_at Timestamp of the group’s last update (does not necessarily indicate changes to any details)
url Group’s web page URL
urlname URL slug of the group (used in URLs)
List

Resource: GET /groups

Returns a paged list of groups. By default, includes all groups available on a calendar, but can be limited using the locality parameters.

The groups can be further limited based on assigned filters.

The result hash includes an array of group objects in the groups key, and a page key with paging information.

Locality Parameters

These parameters restrict the results based on location.

Parameter Type Description Default
campus_id number The community to return groups for all communities
Page Parameters

Specifies the size and offset of the results.

Parameter Type Description Default
page number Page number of results to return, starting with 1 1
pp number Number of groups to return per page (1-100) 10
Filter Parameters

Restrict the returned groups based on the filter items, tags and keywords assigned.

To specify multiple values for type, keyword or exclude_type, the parameter may be repeated with brackets ([]) after the name.

For instance, to request both keyword kw1 and kw2, use a URL similar to: http://CALENDAR-URL/api/2/groups?keyword[]=kw1&keyword[]=kw2.

Parameter Type Description Default
created_after date Only return groups created after this date  
created_before date Only return groups created before this date  
exclude_type number Do not return groups with these filter item IDs  
keyword string Limit groups with keywords or tags  
type number Limit groups to filter item IDs  
Output Parameters

Note: Sorting by distance is only supported when near is specified.

Parameter Type Description Default
all_custom_fields boolean Include all custom fields in the result when true.
By default, only fields visible on the group’s detail page are returned.
false
direction string Change sort order, asc or desc varies
sort string Sort results by
name: group name
created: timestamp of creation
updated: timestamp of last update
name

Example Request: GET http://CALENDAR-URL/api/2/groups

{
  "groups": [
    {
      "group": {
        "id": 3948,
        "name": "CUWinds",
        "urlname": "cuwinds",
        "created_at": "2012-10-09T13:21:45Z",
        "updated_at": "2012-10-10T12:49:41Z",
        "photo_id": null,
        "school_id": 10,
        "campus_id": null,
        "url": "http://www.cuwinds.com/",
        "description_text": "CU WINDS unites Cornell University students who seek remarka...",
        "description": "CU WINDS unites Cornell University students who seek remarka...",
        "filters": {
        },
        "custom_fields": {
        },
        "localist_url": "http://events.cornell.edu/group/cuwinds",
        "photo_url": "http://images-cf.localist.com/images/main/business_huge.png?..."
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 2
  }
}
Get

Resource: GET /groups/GROUP_ID

Returns details about the group specified by group_id.

Parameter Type Description Default
all_custom_fields boolean Include all custom fields in the result when true.
By default, only fields visible on the group’s detail page are returned.
false

Example Request: GET http://CALENDAR-URL/api/2/groups/3948

{
  "group": {
    "id": 3948,
    "name": "CUWinds",
    "urlname": "cuwinds",
    "created_at": "2012-10-09T13:21:45Z",
    "updated_at": "2012-10-10T12:49:41Z",
    "photo_id": null,
    "school_id": 10,
    "campus_id": null,
    "url": "http://www.cuwinds.com/",
    "description_text": "CU WINDS unites Cornell University students who seek remarka...",
    "description": "CU WINDS unites Cornell University students who seek remarka...",
    "filters": {
    },
    "custom_fields": {
    },
    "localist_url": "http://events.cornell.edu/group/cuwinds",
    "photo_url": "http://images-cf.localist.com/images/main/business_huge.png?..."
  }
}
Filters

Resource: GET /groups/filters

Returns the list of group filter items. The ID can be used in the type parameter to /groups.

The parent_id attribute represents the parent filter item, if a child item.

Example Request: GET http://CALENDAR-URL/api/2/groups/filters

{
}
Labels

Resource: GET /groups/labels

Returns the display labels for filter types and custom fields. The key is the identifier (as used in other responses) and value is the user-friendly label.

Example Request: GET http://CALENDAR-URL/api/2/groups/labels

{
  "custom_fields": {
  },
  "filters": {
    "group_types": "Group Types"
  }
}

Department Groups

Provides access to department groups. This resource functions just like groups.

See the groups API for usage details.

Note: Advanced department functionality must be enabled (departments must have their own page) for these APIs to function.

Format
{
  "department": {
    "id": 911,
    "name": "African Studies Program",
    "urlname": "african_studies_program",
    "created_at": "2011-03-07T21:08:35Z",
    "updated_at": "2011-03-07T21:08:35Z",
    "photo_id": null,
    "school_id": 1,
    "campus_id": 11,
    "url": null,
    "description_text": "",
    "description": "",
    "filters": {
    },
    "custom_fields": {
    },
    "localist_url": "http://events.jhu.edu/department/african_studies_program",
    "photo_url": "http://images-cf.localist.com/images/main/business_huge.png?..."
  }
}

See the group format for attribute details.

List

Resource: GET /departments

The result hash includes an array of department group objects in the departments key, and a page key with paging information.

See /groups for details.

Get

Resource: GET /departments/DEPARTMENT_ID

See /groups/GROUP_ID for details.

Filters

Resource: GET /departments/filters

See /groups/filters for details.

Labels

Resource: GET /departments/labels

See /groups/labels for details.

Photos

This resource provides access to photo metadata.

Format
{
  "photo": {
    "id": 60781,
    "business_id": null,
    "caption": "New Mosaic",
    "event_instance_id": null,
    "user_id": 0,
    "neighborhood_id": null,
    "created_at": "2013-04-05T17:59:24Z",
    "updated_at": "2013-04-05T17:59:24Z",
    "location": null,
    "plan_id": null,
    "group_id": null,
    "image_file_name": "4tlRZYDEoGkaf4NI.jpg",
    "image_content_type": "image/jpeg",
    "image_updated_at": "2013-04-05T17:59:24Z",
    "credit": null,
    "width": 576,
    "height": 384,
    "localist_url": "http://events.wtmd.org/photo/60781",
    "photo_url": "http://images-cf.localist.com/photos/60781/huge/a69941856ab8..."
  }
}
Attribute Description
caption Photo caption
created_at Timestamp of photo’s original creation
credit Photo credit
height Height of original image
id Photo ID
image_content_type Content type of original file upload
image_file_name Original filename of upload
image_updated_at Timestamp of last photo image update
localist_url Photo’s URL on Localist (requires authentication to view)
photo_url URL to the image file
updated_at Timestamp of last update
user_id Owner of the photo. This does not necessarily represent the original uploader.
width Width of original image

The following attributes are set when the photo was posted as part of the recent activity stream for an event, place, group or plan.

Attribute Description
business_id Relevant place ID
event_instance_id Relevant event instance ID
group_id Relevant group ID
location Relevant location text (place name, event location)
plan_id Relevant plan ID
List

Resource: GET /photos

Returns a paged result set of all photos.

The result hash includes an array of photo objects in the photos key, and a page key with paging information.

Parameter Type Description Default
page number Page number to return results for, starting at 1 1
pp number Number of photos to return per page, 1-100 10

Example Request: GET http://CALENDAR-URL/api/2/photos

{
  "photos": [
    {
      "photo": {
        "id": 60781,
        "business_id": null,
        "caption": "New Mosaic",
        "event_instance_id": null,
        "user_id": 0,
        "neighborhood_id": null,
        "created_at": "2013-04-05T17:59:24Z",
        "updated_at": "2013-04-05T17:59:24Z",
        "location": null,
        "plan_id": null,
        "group_id": null,
        "image_file_name": "4tlRZYDEoGkaf4NI.jpg",
        "image_content_type": "image/jpeg",
        "image_updated_at": "2013-04-05T17:59:24Z",
        "credit": null,
        "width": 576,
        "height": 384,
        "localist_url": "http://events.wtmd.org/photo/60781",
        "photo_url": "http://images-cf.localist.com/photos/60781/huge/a69941856ab8..."
      }
    }
  ],
  "page": {
    "current": 1,
    "size": 10,
    "total": 76
  }
}
Get

Resource: GET /photo/PHOTO_ID

Returns details about the photo specified by photo_id.

Example Request: GET http://CALENDAR-URL/api/2/photos/60781

{
  "photo": {
    "id": 60781,
    "business_id": null,
    "caption": "New Mosaic",
    "event_instance_id": null,
    "user_id": 0,
    "neighborhood_id": null,
    "created_at": "2013-04-05T17:59:24Z",
    "updated_at": "2013-04-05T17:59:24Z",
    "location": null,
    "plan_id": null,
    "group_id": null,
    "image_file_name": "4tlRZYDEoGkaf4NI.jpg",
    "image_content_type": "image/jpeg",
    "image_updated_at": "2013-04-05T17:59:24Z",
    "credit": null,
    "width": 576,
    "height": 384,
    "localist_url": "http://events.wtmd.org/photo/60781",
    "photo_url": "http://images-cf.localist.com/photos/60781/huge/a69941856ab8..."
  }
}