All for Good

Footprint XML Specification Version 0.1

The Footprint XML Specification is designed for the automated data exchange of volunteer opportunities that are collected by organizations. These organizations are referred to as "providers" as they provide opportunity information to All for Good. Our goal is to organize these opportunities in one place and direct web traffic back to the provider when a user locates a suitable opportunity.

Overall, there are four main stand-alone objects: the FeedInfo, Organization, VolunteerOpportunity, and Review objects. The provider is the source of information for the FeedInfo object; this object specifies the details of the feed being transmitted to Footprint. The Organization object specifies the details of any group involved in the process, whether it be a sponsoring organization (e.g., Habitat for Humanity) or a local volunteer hub that coordinates local opportunities from various organizations. The VolunteerOpportunity object specifies the details of a volunteer opportunity and usually links to at least one organization (e.g., a sponsoring organization and/or a volunteer hub). The Review objects can be reviews of organizations or opportunities.

The spec is based on several existing XML specifications (specifically the specs developed by Network for Good and 1-800-Volunteer for opportunities, and Great Nonprofits for reviews). The major difference is that volunteer organizations and hubs are stand-alone objects to which opportunities refer, thus saving space in the XML document. For instance, if Habitat for Humanity posts 100 opportunities on Idealist, Idealist would create a feed with one Habitat Organization object and 100 VolunteerOpportunity objects, rather than 100 of each. Another difference is the use of the iCal Recurrence Rule format so that repeating opportunities need use multiple dateTimeRecurrance sub-objects to represent one opportunity.

Please note that as of Q4, 2011, now within our existing schema, we have added support for "statewide" and "nationwide" opportunities. As a result, there are now two types of geographically based opportunities: 1)those within a given radius in miles from the search location provided and 2) those that are "statewide" or "nationwide". Statewide or nationwide opportunities are ones that are geographically based in the state or country associated with whatever search location is provided, but that can be performed from anywhere in that state or country. The two types of geographically based opportunities are not intermixed in the search results and must be queried for separately when using the All for Good API via the "type" parameter as described in the All for Good API documentation. Any opportunities that have a state name or state abbreviation value, but no street or city values provided in their location element are assumed to be statewide. The same applies to nationwide opportunities. While few of our data partners are currently sending us "nationwide" opportunities, these are now supported and are automatically included in any statewide search results. Nationwide opportunities cannote be queried for seperately. See the VolunteerOpportunity location element for further detail on how to tag these types of opportunities.

Quick access to objects:

FeedInfo elements
Organization elements
VolunteerOpportunity elements
Review elements
location type elements
dateTimeDuration type elements

Sample data (so you can see the format in action) is available here.

FootprintFeed (element)

The top-level object is FootprintFeed and requires a schemaVersion attribute. Order of objects does not matter. Thus, a feed would be wrapped in the following XML:

<?xml version="1.0" ?> <FootprintFeed schemaVersion="0.1"> ... </FootprintFeed>

FeedInfo (element)
required: at least 1 times
Multiple not allowed

The FeedInfo object contains the information about the feed being delivered from the provider.

providerID (element)
datatype: string

A unique ID for the provider organization. Either a number assigned by Footprint or a URI. Required. No default.
Examples:
<providerID>99</providerID> <providerID>adomainweown.org</providerID>

providerName (element)
datatype: string

Name of organization providing the feed. Required.
Example:
<providerName>Volunteer Opportunity Aggregators</providerName>

feedID (element)
required: optional.
datatype: string

Only needed if the provider delivers multiple, mutually exclusive feeds (can be URI). Optional. Default is "0".
Example:
<feedID>1</feedID>

createdDateTime (element)
datatype: dateTimeOlsonDefaultPacific

The date+time (Olson time zone attribute optional, default is "America/Los_Angeles" which represents the U.S. Pacific time zone) that this specific iteration of the feed was created. Required. No default.
Examples:
<createdDateTime olsonTZ="Etc/UTC">2009-08-02T09:24:34</createdDateTime> <createdDateTime olsonTZ="America/New_York">2009-03-02T09:24:34</createdDateTime>

providerURL (element)
required: optional.
datatype: string

URL to the provider organization's homepage. Optional. No default.
Example:
<providerURL>www.voloppaggregator.org</providerURL>

termsOfUse (element)
required: optional.
datatype: string

Terms of use. Optional. Recommended. No default.
Examples:
<termsOfUse>Public Domain.</termsOfUse> <termsOfUse>See terms of use on our website: www.voloppaggregator.org/terms.html</termsOfUse>

description (element)
required: optional.
datatype: string

Any notes about the feed. Optional. Not recommended. No default.
Examples:
<description>This feed contains all volunteer opportunities from Volunteer Opportunity Aggregators. </description> <description>This feed contains only virtual volunteer opportunities from Volunteer Opportunity Aggregators. See feed with feedID=2 for physical opportunities. </description>

Organizations (element)
required: optional.

The Organizations object wraps a set of Organization objects. Order of Organization objects has no semantic meaning.

Organization (repeated element)
required: optional.

The Organization object represents any organization involved in the non-profit process (specifically volunteer hubs count as organizations). Organization objects are wrapped in an Organizations. Order of fields does not matter.

organizationID (element)
datatype: string

Unique ID within the feed. Most likely a number (from a database primary key) but can be a URI. Required. No default. Would be helpful if it were constant across feeds from one provider.
Examples:
<organizationID>57</providerID> <organizationID>genericvolorg.org</organizationID>

nationalEIN (element)
datatype: string
required: optional.

National Employer Identification Number. Optional. No default.
Example:
<nationalEIN>91-1914867</nationalEIN>

guidestarID (element)
datatype: integer
required: optional.

ID number from guidestar.org. Optional. No default. Cannot be blank.
Example:
<guidestarID>91</guidestarID>

name (element)
datatype: string

Name of the organization. Required. No default.
Example:
<name>American Helpers United</name>

missionStatement (element)
datatype: string
required: optional.

Mission statement of organization. Optional. No default.
Example:
<missionStatement>Change the world. Do good.</missionStatement>

description (element)
datatype: string
required: optional.

Description of organization. Optional. No default.
Example:
<description>Based in Faketown, VA, we help people change the world and do good things.</description>

location (element)
datatype: locationType
required: optional.

Physical location of organization. See locationType for type definition. Optional, but recommended at the city/regional/postalCode level. No default.
Example:
<location> <virtual>no</virtual> <streetAddress1>45 W 3rd St</streetAddress1> <city>Faketown</city> <region>VA</region> <postalCode>22322</postalCode> </location>

phone (element)
datatype: string
required: optional.

Phone number (and extension) of organization. Optional. No default. Not expected from most providers.
Examples:
<phone>121-555-1212</phone> <phone>1215551212</phone> <phone>44 844 394 0 787</phone>

fax (element)
datatype: string
required: optional.

Fax number of organization. Optional. No default. Not expected from most providers.
Examples:
<fax>121-555-1213</fax> <fax>1215551213</fax>

email (element)
datatype: string
required: optional.

Email of organization. Optional. No default. Not expected from most providers.
Example:
<email>contact@coolvols.org</email>

organizationURL (element)
datatype: string
required: optional.

URL of the organization's homepage. Optional. No default.
Example:
<organizationURL>www.coolvols.org</organizationURL>

donateURL (element)
datatype: string
required: optional.

URL of the organization's donation page. Optional. No default.
Example:
<donateURL>www.coolvols.org/donate</donateURL>

logoURL (element)
datatype: string
required: optional.

URL of the organization's logo. Optional. No default. Dimensions are TBD.
Example:
<logoURL>www.coolvols.org/logo.gif</logoURL>

detailURL (element)
datatype: string
required: optional.

URL of the organization's page on the providers site. Optional. No default. Highly recommended.
Examples:
<detailURL>www.awesomevolaggergator.org/orgs.php?id=3</detailURL> <detailURL>www.anothervolaggergator.org/coolvols.html</detailURL>

VolunteerOpportunities (element)
required: optional.

The VolunteerOpportunities object wraps a set of VolunteerOpportunity objects. Order of VolunteerOpportunity objects has no semantic meaning.
Example:
<VolunteerOpportunities> <VolunteerOpportunity>   ... </VolunteerOpportunity> <VolunteerOpportunity>   ... </VolunteerOpportunity> </VolunteerOpportunities>

VolunteerOpportunity (repeated element)
required: optional.

The VolunteerOpportunity object represents one volunteer opportunity listing. It is capable of representing a repeating or ongoing event. Often an Opportunity object will link to an Organization object via the sponsoringOrganizationID or volunteerHubOrganizationID fields. Order of fields does not matter.

volunteerOpportunityID (element)
datatype: string

Unique ID within the feed. Often a primary key from a database, but can be a URI. Required. No default.
Examples:
<volunteerOpportunityID>157</volunteerOpportunityID> <volunteerOpportunityID>urn:fpvol:101-001-157</volunteerOpportunityID>

sponsoringOrganizationIDs (element)
required: optional.

Wrapper for sponsoringOrganizationID fields to allow multiple sponsoring organizations. Order does matter semantically and indicates the order that the sponsors should be shown (i.e., first sponsor is lead sponsor). Optional. Recommended.

sponsoringOrganizationID (repeated element)
datatype: string
required: optional.

Link to an Organization object that relates to this opportunity as the sponsoring organization via the organizationID field. Most opportunities will have an associated sponsoringOrganizationID, which funds and/or conducts the opportunity. Optional. Recommended. If present, must be the same as exactly one Organization.organizationID value in the same field.
Example:
<sponsoringOrganizationIDs> <sponsoringOrganizationID>57</sponsoringOrganizationID> </sponsoringOrganizationIDs>

volunteerHubOrganizationIDs (element)
required: optional.

Wrapper for volunteerHubOrganizationID. Semantic order of volunteerHubOrganizationID fields does not matter.

volunteerHubOrganizationID (repeated element)
datatype: string
required: optional.

Link to an Organization object that relates to this opportunity as the local volunteer hub via the organizationID field. In contrast to the sponsoring organization, the volunteer hub is the organization that coordinates many local opportunities conducted by several sponsoring organizations. A minority of opportunities will have a volunteer hub associated with them, so if you are confused by this field, that's fine, you probably do not have the data in your database. Optional. No default. If present, must be the same as exactly one Organization.organizationID value in the same field.
Example:
<volunteerHubOrganizationID> <volunteerHubOrganizationID>genericvolorg.org</volunteerHubOrganizationID> </volunteerHubOrganizationID>

title (element)
datatype: string

Short title of the opportunity. Required. No default.
Examples:
<title>Help at the Newville Shelter</title> <title>Plant some Trees in Widerton</title>

abstract (element)
datatype: string
required: optional.

Examples:
<abstract>Help cook, pass out food and clean at the Newville Shelter. Every Sunday at 10am to noon. Bring friends.</abstract> <abstract>Come to Widerton park and plant trees this Sunday, April 19th, 2:00pm. Sponsored by the local SAVE organization. Bring gloves.</abstract>

volunteersNeeded (element)
datatype: integer
required: optional.

How many volunteers are needed for this opportunity. Special codes: -999 for unlimited. -8888 for unknown number of volunteers. Other than those exceptions, must be a non-negative integer. Optional. Default is -8888 to represent unknown number of volunteers. Cannot be blank. May not be up-to-date as volunteers sign up. Design decision: large negative numbers for special codes since overbooking might lead to accidental use of negative numbers.
Examples:
<volunteersNeeded>10</volunteersNeeded> <volunteersNeeded>-999</volunteersNeeded> <volunteersNeeded>-8888</volunteersNeeded>

rsvpCount (element)
datatype: integer
required: optional.

How many people have signed up for this event (through partner's website). Special codes: -8888 for unknown. Other than that exception, must be a non-negative integer. Optional. Default is -8888 to represent unknown number of rsvp's. Cannot be blank. May not be up-to-date as volunteers sign up.
Examples:
<rsvpCount>5</rsvpCount> <rsvpCount>-8888</rsvpCount>

dateTimeDurations (element)

A wrapper around one or more dateTimeDuration sub-objects. See the sub-object documentation. Given the recurrence field in dateTimeDuration sub-object, the vast majority of cases should only need one dateTimeDuration sub-object. Order of dateTimeDuration objects has no semantic meaning. Required.

dateTimeDuration (repeated element)
datatype: dateTimeDurationType
required: at least 1 times

Represents the dates/timing of the event. Has a recurrence element for repeated opportunities. Required. Order of fields does not matter.
Example of one-time event:
<dateTimeDurations> <dateTimeDuration>   <openEnded>No</openEnded>   <startDate>2009-04-19</startDate>   <endDate>2009-04-19</endDate>   <startTime olsonTZ="America/Chicago">14:00:00</startTime>   <endTime olsonTZ="America/Chicago">16:00:00</endTime> </dateTimeDuration> </dateTimeDurations>
Example of two-time (in this case, two-day) event:
<dateTimeDurations> <dateTimeDuration>   <openEnded>No</openEnded>   <startDate>2009-04-18</startDate>   <endDate>2009-04-18</endDate>   <startTime olsonTZ="America/Chicago">14:00:00</startTime>   <endTime olsonTZ="America/Chicago">16:00:00</endTime> </dateTimeDuration>   <openEnded>No</openEnded>   <startDate>2009-04-19</startDate>   <endDate>2009-04-19</endDate>   <startTime olsonTZ="America/Chicago">14:00:00</startTime>   <endTime olsonTZ="America/Chicago">16:00:00</endTime> </dateTimeDuration> </dateTimeDurations>
Same example, but using the iCalRecurrance to specify a two-day event:
<dateTimeDurations> <dateTimeDuration>   <openEnded>No</openEnded>   <startDate>2009-04-18</startDate>   <endDate>2009-04-19</endDate>   <startTime olsonTZ="America/Chicago">14:00:00</startTime>   <endTime olsonTZ="America/Chicago">16:00:00</endTime>   <iCalRecurrence>FREQ=DAILY;COUNT=2</iCalRecurrence> </dateTimeDuration> </dateTimeDurations>
Example of using the iCalRecurrance to specify a biweekly Tuesday meeting, open-ended:
<dateTimeDurations> <dateTimeDuration>   <openEnded>Yes</openEnded>   <startTime olsonTZ="America/New_York">17:00:00</startTime>   <endTime olsonTZ="America/New_York">18:00:00</endTime>   <iCalRecurrence>FREQ=WEEKLY;INTERVAL=2;WKST=SU;BYDAY=TU</iCalRecurrence> </dateTimeDuration> </dateTimeDurations>
Example of an open inviation to come in during business hours for a day:
<dateTimeDurations> <dateTimeDuration>   <openEnded>No</openEnded>   <startDate>2009-04-16</startDate>   <endDate>2009-04-16</endDate>   <startTime olsonTZ="America/New_York">09:00:00</startTime>   <endTime olsonTZ="America/New_York">17:00:00</endTime>   <timeFlexible>Yes</timeFlexible> </dateTimeDuration> </dateTimeDurations>
Example of a flexible, commitment of 2 months, with 10 hours of work per week:
<dateTimeDurations> <dateTimeDuration>   <openEnded>Yes</openEnded>   <duration>P2M</duration>   <timeFlexible>Yes</timeFlexible>   <commitmentHoursPerWeek>10</commitmentHoursPerWeek> </dateTimeDuration> </dateTimeDurations>

locations (element)
required: optional.

A wrapper around one or more location sub-objects. See the sub-object documentation. Order of location objects matters only in that the first location is the default time zone if the time zone for the opportunity start or end time is unspecified. Required, unless volunteerHubOrganizationID is present and that Organization object has location informaion.

location (repeated element)
datatype: locationType
required: optional.

Represents where the opportunity is physically located, if it is statewide, if it is nationwide, or if it is virtual (non-physical) opportunity. May use multiple location elements to represent multiple opportunity sites. Required, unless volunteerHubOrganizationID is present and that Organization object has location informaion. Order of fields does not matter. If you have microvirtual or self-directed/how-to guide type opportunities these should be setup in seperate feed files from your other types of opportunities and and should not have their location element populated.
Example of one physical location:
<locations> <location>   <virtual>No</virtual>   <name>Widerton Homless Shelter</name>   <streetAddress1>10 City Ln</streetAddress1>   <city>Widerton</city>   <region>VA</region>   <postalCode>22003</postalCode>   <directions>Use door on the First St side of building</directions> </location> </locations>
Example of an event taking place in two physical locations:
<locations> <location>   <virtual>No</virtual>   <name>Widerton Homless Shelter</name>   <streetAddress1>10 City Ln</streetAddress1>   <city>Widerton</city>   <region>VA</region>   <postalCode>22003</postalCode> </location> <location>   <virtual>No</virtual>   <name>Narrowton Homless Shelter</name>   <streetAddress1>101 Park St</streetAddress1>   <city>Narrowton</city>   <region>VA</region>   <postalCode>22004</postalCode> </location> </locations>
Example of a statewide opportunity:
<locations> <location>   <virtual>No</virtual>   <name>Virginia</name>   <region>VA</region> </location> </locations>
Example of a nationwide opportunity:
<locations> <location>   <virtual>No</virtual>   <country>Canada</country> </location> </locations>
Example of a virtual event (such as online translation help):
<locations> <location>   <virtual>Yes</virtual> </location> </locations>

paid (element)
datatype: yesNoEnum
required: optional.

Does the opportunity pay volunteers. Domain is {"Yes" | "No"}. Optional. Default is "No".

audienceTags (element)
required: optional.

A wrapper for one or more audienceTag fields. An audienceTag field is a string that describes a group of people who would be appropriate volunteers. There is no set domain for the audienceTag field. Optional. Order of audienceTag entries has no semantic meaning.

audienceTag (repeated element)
datatype: string
required: optional.

String that represents a target audience. No domain. Optional. No default.
Example of a two-audience event:
<audienceTags>    <audienceTag>Teens</audienceTag>    <audienceTag>College-aged</audienceTag> </audienceTags>

categoryTags (element)
required: optional.

A wrapper for one or more categoryTag fields. A categoryTag field is a short string that describes the opportunity. Keywords also belong here, as categoryTag fields. There is no set domain for the categoryTag field. Order of categoryTag entries has no semantic meaning.

categoryTag (repeated element)
datatype: string
required: optional.

String that represents a category of the opportunity or a keyword/phrase of the opportunity. No domain. Optional. No default. Recommended.
Example of a three-category event:
<categoryTags>    <categoryTag>Homeless</categoryTag>    <categoryTag>Hunger</categoryTag>    <categoryTag>Weekend opportunity</categoryTag> </categoryTags>

minimumAge (element)
datatype: integer
required: optional.

The minimum age of volunteers. Optional. Recommended. Cannot be blank.
Examples:
<minimumAge>18</minimumAge> <minimumAge>7</minimumAge> <minimumAge>50</minimumAge>

sexRestrictedTo (element)
datatype: sexRestrictedEnum
required: optional.

Is the opportunity restricted to one sex/gender. Domain: {"Female" | "Male" | "Neither"}. Optional. Default is "Neither".
Examples:
<sexRestrictedTo>Neither</sexRestrictedTo> <sexRestrictedTo>Female</sexRestrictedTo> <sexRestrictedTo>Male</sexRestrictedTo>

skills (element)
datatype: string
required: optional.

String of all the skills a volunteer needs. One (potentially long) string. Optional. Recommended. No default.
Examples:
<skills>Able-bodied.</skills> <skills>Be able to translate Spanish to English and back. Must be able to work remotely via the Internet.</skills>

contactName (element)
datatype: s