Skip to content

IcalLocation

Jump to bottom Edit New page
Shawna C Scott edited this page Jul 27, 2014 · 2 revisions

How iCal represents location

**Labels:**Phase-Design,Phase-Implementation,iCal,Venue

To do

  • Add discussion of issues in VVENUE spec.

Contents

Summary

An iCalendar may include information about event location in three places:

LOCATION is an optional property that is simple and unstructured relative to VVENUE. GEO is an optional property that provides only latitude/longitude. Public web calendars (e.g., Eventful, Meetup, Upcomgin) typically use both LOCATION and GEO.

A proposed RFC includes the separate, optional VVENUE component. VVENUE is complex and structured (relative to LOCATION). For instance, VVENUE may include separate NAME, STREET-ADDRESS, TEL, and GEO properties. Some public calendars systems partly implement VVENUE.

To the extent that calendars use VVENUE, we could extract venue information relatively easily.

To the extent they use LOCATION, we could extract unstructured text relatively easily. But extracting specific venue details -- for instance, the address -- would require more intelligent parsing.

GEO information is easy to find and extract, but is limited. It could, however, be useful for finding venues by distance. It might be helpful in de-duping venues.

iCal specification

The adopted iCalendar specification, RFC 2445 (November 1998), uses LOCATION to identify event venue and GEO to identify latitude/longitude. A proposed revision to RFC 2445 -- RFC 2445bis (Rev. 08 Feb. 2008) does not propose changes to the LOCATION property.

A draft specification, draft-norris-ical-venue-01 (revised Aug. 1, 2007), proposes a VVENUE parameter and component. Eventful feeds implement an earlier version of VVENUE. Upcoming implements VVENUE but does not fully comply with the draft specification.

iCal LOCATION property

The iCal LOCATION property defines the event venue. It is specified by iCal spec 4.8.1.7.

It is an optional property. It occurs within the VEVENT component. (It may also occur within a VTODO component.) It takes the form

LOCATION optional parameters**:**text CRLF

The optional parameters are:

; ALTREP="URI" (must not occur more than once) followed by

; LANGUAGE=language abbrv from RFC 1766 (must not occur more than once) followed by

; experimental parameter = value, value ... (experimental parameter may occur any number of times and take 1 or more arguments)

Examples:

  • LOCATION;LANGUAGE=en:Germany
  • LOCATION;LANGUAGE=no:Tyskland
  • LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":Conference Room - F123, Bldg. 002
  • LOCATION:Conference Room - F123, Bldg. 002

Line length

As with other parts of the iCal object, lines should be no longer than 75 octects. Longer lines should be "folded" by inserting a CRLF followed by white space. For example:

     DESCRIPTION:This is a long description that exists on a long line.

   Can be represented as:

     DESCRIPTION:This is a lo
      ng description
       that exists on a long line.

See RFC 2445 Section 4.1.

Here is the entire iCal spec 4.8.1.7:

  4.8.1.7 Location

   Property Name: LOCATION

   Purpose: The property defines the intended venue for the activity defined by a calendar component.

   Value Type: TEXT

   Property Parameters: Non-standard, alternate text representation and language 
     property parameters can be specified on this property.

   Conformance: This property can be specified in "VEVENT" or "VTODO" calendar component.

   Description: Specific venues such as conference or meeting rooms may be explicitly 
     specified using this property. An alternate representation may be specified that 
     is a URI that points to directory information with more structured specification 
     of the location.  For example, the alternate representation may specify either an 
     LDAP URI pointing to an LDAP server entry or a CID URI pointing to a MIME body part 
     containing a vCard [RFC 2426] for the location.

   Format Definition: The property is defined by the following notation:

     location   = "LOCATION locparam ":" text CRLF

     locparam   = `*`(

                ; the following are optional,
                ; but MUST NOT occur more than once

                (";" altrepparam) / (";" languageparam) /

                ; the following is optional,
                ; and MAY occur more than once

                (";" xparam)

                )

   Example: The following are some examples of this property:
  
  LOCATION:Conference Room - F123, Bldg. 002

  LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":Conference Room - F123, Bldg. 002

ical GEO property

Specifies latitude and longitude (in that order) in decimal degrees. Example

GEO:37.386013;-122.082932

Draft iCal VVenue Specification

A draft specification, draft-norris-ical-venue-01 (revised Aug. 1, 2007), describes proposed venue support for iCalendar. It was proposed by the Eventful developers, and their feeds implement it. Upcoming implements it improperly.

A VVENUE component is an iCal component that describes a venue. A VEVENT may be related to venue by using a VVENUE parameter inside the LOCATION property of the VEVENT, with a unique identifier like so:

LOCATION;[email protected]:The Venue\n1055 Fifth Avenue\nSan Diego, CA 92101

The VVENUE parameter refers to a separately defined VVENUE component.

It appears that the iCal hierarchy is:

  object (example: VCALENDAR)
    component (examples: VEVENT  or VVENUE component of VCALENDAR)
      property (example: LOCATION property of VEVENT)
        parameter (examples: ALTREP or VVENUE property of LOCATION)

The VVENUE component is at the same level as the VEVENT component. It must not nested within the VEVENT.

VVENUE component definition

Here is the VVENUE component definition from WIKI PARSE WARNING: unterminated backtick! draft RFC section 5

5.  Venue Component

   Component Name: "VVENUE"

   Purpose: Provide a grouping of component properties that describe an
   event venue.

   Format Definition: A "VVENUE" calendar component is defined by the
   following notation:
     venuec  = "BEGIN" ":" "VVENUE" CRLF
             venueprop
             "END" ":" "VVENUE" CRLF

     venueprop  = *(

               ; the following are all REQUIRED,
               ; but MUST NOT occur more than once

               uid

               ; the following are optional,
               ; but MUST NOT occur more than once

               name / description / street-address / extended-address /
               locality / region / country / postal-code / tzid / geo /
               location-type / categories

               ; the following are optional,
               ; and MAY occur more than once

               tel / url
             )

   Description: A "VVENUE" calendar component is a grouping of component
   properties that represent a venue where an event occurs.  This
   extends the "LOCATION" property of "VEVENT" and "TODO" components,
   providing the ability to specify detailed information about the event
   venue.

   Example: The following is an example of the "VVENUE" calendar
   component used to represent the The Venue in San Diego, California.

   BEGIN:VVENUE
   VENUE-ID:[email protected]
   NAME:The Venue
   DESCRIPTION: The Venue is a home for live music
     and southern-inspired cuisine in an environment celebrating the
     African American cultural contributions of blues music and folk
     art.
   STREET-ADDRESS:1055 Fifth Avenue\nSuite 4
   EXTENDED-ADDRESS:Stage 2
   LOCALITY:San Diego
   REGION;ABBREV=CA:California
   COUNTRY;ABBREV=US;ABBREV=USA:United States
   POSTAL-CODE:92101
   TZID=US/Pacific
   GEO:32.716220;-117.160156
   URL;TYPE=map:http://maps.example.com/maps?q=1055%20Fifth%20Avenue%
     2C%20San%20Diego%2C%20California%20&hl=en
   URL;TYPE=Event Listing:http://events.example.com/venues/V0-001-00015
     3774-0
   URL;TYPE=Official Site:http://thevenue.com/venues/clubvenues/sandi
     ego/
   TEL;TYPE=Box Office:619.299.2583
   CATEGORIES:music concert
   END:VVENUE

Complete VEVENT and VVENUE example

And here is an example with both a VEVENT and a VVENUE:

BEGIN:VCALENDAR
PRODID:-//Example Co.//Example 2.0//EN
VERSION:2.0
BEGIN:VTIMEZONE
TZID:US/Pacific
LAST-MODIFIED:20060110T171418Z
BEGIN:STANDARD
DTSTART:20051030T080000
TZOFFSETTO:-0700
TZOFFSETFROM:+0000
TZNAME:MST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:20060402T020000
TZOFFSETTO:-0600
TZOFFSETFROM:-0700
TZNAME:MDT
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
UID:[email protected]
LOCATION;[email protected]:The Venu
  e\n1055 Fifth Avenue\nSan Diego, CA  92101
DTSTAMP:20060110T171344Z
DTSTART;TZID=US/Pacific:20060717T200000
SUMMARY:Joe Bloggs in concert
DTEND;TZID=US/Pacific:20060717T2300000
DESCRIPTION:Joe Bloggs plays everything from the old
  Pieman & Garfunkie stuff to his latest album. Not to be
  missed!
END:VEVENT
BEGIN:VVENUE
VENUE-ID:[email protected]
NAME:The Venue
DESCRIPTION: The Venues is a home for live music and
  southern-inspired cuisine in an environment celebrating
  the Afric an American cultural contributions of blues
  music and folk art.
STREET-ADDRESS:1055 Fifth Avenue\nSuite 4
EXTENDED-ADDRESS:Stage 2
LOCALITY:San Diego
REGION;ABBREV=CA:California
COUNTRY;ABBREV=US;ABBREV=USA:United States
POSTAL-CODE:92101
TZID=US/Pacific
GEO:32.716220;-117.160156
URL;TYPE=Map:http://maps.example.com/maps?q=1055%20Fifth
  %20Avenue%2C%20San%20Diego%2C%20California%20&hl=en
URL;TYPE=Event Listing:http://events.example.com/venues/
  V0-001-000153774-0
URL;TYPE=Official Site:http://thevenue.com/venues/clubvenues
  /sandiego/
TEL;TYPE=Box Office:619.299.2583
CATEGORIES:music concert
END:VVENUE
END:VCALENDAR

Examples from real iCal calendars

Eventful

Here is part of a single event exported from Eventful into iCal format. It uses both the LOCATION property and the VVENUE component, but does not comply with the most recent version (Aug. 2007) of the VVENUE RFC because it names the VVENUE id proprety UID instead of VENUE-ID:

BEGIN:VCALENDAR
.....
BEGIN:VEVENT
.....
SUMMARY:Portland Macintosh Users Group (PMUG)
DESCRIPTION:Portland Macintosh Users Group (PMUG) meets the 2nd monday
     of every month 2006 & 2007\n\nWeb Site: http://www.pmug.org\n\nContac
    t Information: Peren Bjork [email protected]\n
LOCATION;[email protected]:Ecotrust @ Jean Vollum
     Natural Capital Center, Portland, Oregon 97209 United States
.....
END:VEVENT
BEGIN:VVENUE
X-VVENUE-INFO:http://evdb.com/docs/ical-venue/draft-norris-ical-venue.
    html
UID:[email protected]
NAME:Ecotrust
ADDRESS:Jean Vollum Natural Capital Center
CITY:Portland
REGION;ABBREV=OR:Oregon
COUNTRY;ABBREV=USA:United States
POSTALCODE:97209
GEO:45.532;-122.684
URL;X-LABEL=Venue Info:http://eventful.com/V0-001-000360625-7
END:VVENUE
END:VCALENDAR

Meetup

Here is part of a calendar exported from Meetup into iCal format. (Thanks to Sam L-G.) It uses the LOCATION property and the GEO property, but not the VVENUE component.

BEGIN:VCALENDAR
.....
BEGIN:VEVENT
...
LOCATION:OTBC - 15455 NW Greenbrier Pkwy\, Suite 210 - Beaverton\, OR  9
 7006 - USA
.....
GEO:45.52\;-122.86
.....
END:VEVENT
END:VCALENDAR

Upcoming

Here is part of a calendar exported from Upcoming into iCal format. It uses both the LOCATION property and the VVENUE component. It does not fully comply with the most recent (Aug. 2007) proposed VVENUE RFC because:

  • In the VEVENT LOCATION, it uses the name VENUE-UID instead of VVENUE and
  • In the VVENUE, it does not include the VENUE-ID property. (It does, however, have a URL;X-LABEL=Venue Info: with the same text as in the VENUE-UID.
BEGIN:VCALENDAR
.....
BEGIN:VEVENT
.....
SUMMARY:Portland Web Innovators - Getting Down to Business in March
.....
ORGANIZER;CN=duvander:X-ADDR:http://upcoming.yahoo.com/user/48972/
LOCATION;VENUE-UID="http://upcoming.yahoo.com/venue/113104/":Needmore Designs @ 107 SE Washington\, Suite 265\, Portland\, Oregon US
END:VEVENT
BEGIN:VVENUE
X-VVENUE-INFO:http://evdb.com/docs/ical-venue/draft-norris-ical-venue.html
NAME:Needmore Designs
ADDRESS:107 SE Washington\, Suite 265
CITY:Portland
REGION;X-ABBREV=or:Oregon
COUNTRY;X-ABBREV=us:United States
POSTALCODE:
GEO:45.5188;-122.665
URL;X-LABEL=Venue Info:http://upcoming.yahoo.com/venue/113104/
END:VVENUE
END:VCALENDAR

Issues

  • Eventful includes VVENUEs in iCal exports, but uses UID (specified in an earlier version of the draft VVENUE RFC) instead of VENUE-ID.
  • Upcoming includes VVENUEs in their iCalendar feeds, but does not include a VENUE-ID in them (as required by the spec). They put a copy of the venue after every item in the feed, and include a URL;X-LABEL=Venue Info: that matches the text of the VENUE-UID. When reading venues from Upcoming feeds, we would have to associate venues to events sequentially, or match the VENUE-ID with the URL;X-LABEL=Venue Info:.
  • Someone who complies with the spec could create a file with all events or venues grouped at the end, or with one venue listing for many events.
  • The VVENUE RFC is still a draft. It might not be adopted, and it could be changed before adoption (although changes are likely to be minor).

INITIAL REVIEW NEEDED

Add a custom footer
Clone this wiki locally