Best Practices for Third-Party Applications

The following is an official set of best practices for third party applications to follow. It does get reasonably technical, so be forewarned. If you're just looking for easier ways to syndicate data on your site, look to RSS, iCal, or Badges.

Commercial Use

We currently restrict the use of the API to non-commercial use only. Commercial users must contact us first for permission before using or developing on the API.

Query-Based Apps

This section covers query-based applications - i.e. visualizations of Upcoming.org events, mashups that query for events or venues, etc.

Query Chaining

Due to the current API's architecture, you'll need to query the API multiple times in order to collect a full set of data about an event, including venue and address information. Future revisions will make it simpler to obtain the full description with fewer queries. However, for the time being, the way that we recommend performing these queries is to use the comma-separated ID syntax supported by the *.getInfo methods. This feature allows you to pass a list of ID's, separated by commas, as opposed to a single ID per method call. A basic prototype of query API interaction would be as follows:

1. Search for Events using the event.search method. [Returns a bunch of events with venue_ids]
2. Collect all the Venue ID's and assemble a comma-separated list.
3. Call venue.getInfo with the CSL of Venue ID's. [Returns a bunch of venues with metro_ids]
4. Collect all the Metro ID's and assemble a CSL.
5. Call metro.getInfo with the CSL of Metro ID's. [Returns a bunch of metros, etc...]
6. Repeat as necessary...
7. Assemble all your data together and present to the user.

As I mentioned earlier, this will be reduced to fewer calls in the near future.

Query Caching

For API-based apps that display a single, relatively static set of information, caching your queries will provide fast rendering to your users while reducing the total number of calls and traffic between your app and Upcoming.org. This is especially important for badge-style displays of data on other websites. Using a memory cache like memcached is very helpful and recommended for these types of applications.

Posting New Data to Upcoming.org

This section deals with third party apps that post new data to Upcoming.org using the API.

Development and Testing

We strongly that any development or test data that gets added to Upcoming.org via the API be sent over marked as 'private' or 'personal'. This will effectively prevent junk or test data from being posted to the public view. If we notice junk data being added as public, we may disable your API key!

Avoiding Errors and Typos

We recommend that preview functionality be built into any application so that users may preview their own data before posting it to our database. Because their ability to edit or delete data is limited, it's important to verify the information before posting.

Avoiding Duplicates

Your API-based application should endeavor to check for possible duplicates or similar events before posting any event/venue/metro data to our database. Apps should make diligent use of the *.search methods after or during data entry or preview, before final commit of data to Upcoming.org. This will help keep the Upcoming.org database free of duplicates. Future improvements to our data structure and API will make this easier soon.

Don't Share Usernames

Upcoming.org works best as a social application. Make sure that anyone posting data to Upcoming.org is doing it with their own personal user account, and not with a batch or shared account. Sharing accounts won't allow us to distinguish between people who are posting good data via the API and people who are using the API to spam Upcoming.org.