Top API Users 
UserSite Name API Calls Bytes Sent Searches Details Total Run Time Last Run Time
A4 http://www.EventLister.com 32921 1.6 GB 16298 16623 31 hours 4 hours
A405071 http://findpopups.com 2 7 kB 0 2 0 seconds 44 days
A356822 http://ipictdb.com 4708 82.0 MB 4702 6 13 minutes 5 months
A368106 http://staging.mysocialgps.com/ 1 74 kB 1 0 0 seconds 14 months
A358697 http://mysocialgps.phpdevelopment.co.in 48 11.2 MB 46 2 30 seconds 18 months
A307997 http://www.festivalclick.com 139 240.5 MB 136 3 39 minutes 23 months
A135700 http://www.MyFairsAndFestivals.com/ 727698 1.9 GB 35265 692433 6 days 2 years
A345636 http://randywoolard.net 1817 382.6 MB 1738 79 34 minutes 2 years
A266269 http://freecityinfo.com 503 564.9 MB 450 53 94 minutes 2 years
A271897 http://culturemob.com 1753 1.9 GB 1052 701 6 hours 3 years
A273833 http://www.rboq.com/event 473 84 kB 0 473 3 minutes 3 years
A326225 http://www.rvtripsusa.com 55 2.2 MB 46 9 48 seconds 3 years
A326048 http://sidewaysent.com/ 35 3.2 MB 0 35 37 seconds 3 years
A214863 http://Eventful.com 1308 7.9 MB 1308 0 4 hours 4 years
A262711 http://www.FairsAndFestivals.net/ 26630 709.3 MB 3601 23029 26 hours 4 years

 EventLister.com XML API Overview 
The XMl API allows other sites to access our raw event listing data for re-display and to contribute listings to our main database. If you are not able to write code that can run on your webserver, you can not use this API, try one of the methods to link to results directly or through an IFRAME.

There is also a XML interface for Google Homepage Modules. This will let you add an EventLister.com Event Search Box to your Personalized Google Homepage. Site developers can certainly work with this feed too though!

Existing Methods:
EventSearch - Returns event listings matching query
EventDetails - Returns details on an event listing

Planned Methods:
EventAdd - Adds an event to our database
SendMessage - Lets your users send messages to our crafters and promoters


Full Documentation


 Signup as an API User 
To use the EventLister.com XML API Interface, you must register for a Key. This is free and the registration process adds your site to a directory of sites that our users see.

Register Now!

 API Version 1 Documentation 
Current Version: v1 documentation (same as below) - released 11/2008
Previous Version: v0.1b documentation


EventLister.com XML API

The purpose of this API is to allow other sites to display listings of events in their area or to intermingle our listings with any they may already have. The API allows free access to the raw data for all events upcoming within the next 6 months in easily parsed XML format. It is hoped that many Tourism sites, Newspaper sites, Community Event sites, Competitors' sites, Printed Guides/Directories etc. take advantage of this API - giving more exposure to all events in the long run. Please spread the word!

API - Abbreviation of Application Program Interface, a set of routines, protocols, and tools for building software applications. In this case, the EventLister.com API is a public interface around the EventLister.com site/database/program, allowing derivative works and re-publishing of our event listings within other sites or applications. more info on APIs

XML - Extensible Markup Language is used to pass data in and out. more info on XML

Tems of Use / License Agreement

Use of any data or information obtained through this API is subject to the following restrictions:
  • Data returned from the API is not yours, you are only given rights to re-display or re-publish returned data while you are a good-standing, current API user. If you stop using the API (collecting updates) or are banned from it you will no longer have rights to use, re-display, or re-publish any data ever obtained through it. Legal recourse will be sought for violations.
  • You CAN sell access to this data. You CAN create derivative commercial works from this data and using this API. You may charge for access to this data and derivative works only so long as your billing practices are not deceptive. You can not automatically rebill customers and you can not offer lower introductory rates unless we review and approve of your entire billing process.
  • You must keep your copy up to date. You can not re-publish data obtained through this API if you have not checked for updates in a week, preferably much sooner. Obviously if you are banned for the API, you can not retrieve updates and must stop publishing our data. Continued use of data by an inactive or banned user will result in legal recourse. We do not want invalid info persisting anywhere.
  • Event data returned is allowed to be cached by you (unless stated), meaning you can create your own database of event listing data to run your site from (searches, event details) and then just pull updates periodically to your own database copy. The EventImage, EventApplicationImage, and EventWebsiteForwarder are not cachable - any form of caching will result in banning.
  • THE API USAGE LISENCE REQUIRES THAT YOU SHOW EVERYWHERE THAT A LISTING IS APPROXIMATE, if it is so marked with us via the Output variable <DateTrust>, unless you HAVE confirmed the date!! This includes in search results. You must say on the event's details page that the date is 'Approximate Only' in colored text, near the date. You must use in search results at minimum a symbol or icon that is colored, near the date, and that links to a key/legend explaning the symbol means an event's date is 'Approximate Only'. Here, we use a red @ that links to an explination via a key/legend of the red @. If you display ONE of our approximate-marked listings without indication that it IS only approximate and is unconfirmed to be happening or when, you will be assumed to be intentionally portraying inaccurate information as accurate in an attempt to force/garner more user signups to your site, and will be banned from API use.


Overview
  • Each method has a unique URL and can be called over HTTP or HTTPS.
  • Variables and URLs are CaSe SENsitiVE!
  • Variables are passed in as HTTP variables. i.e. url.htm?Var1=A&Var2=Cya
  • Results are the content of the method HTTP request and are in XML format.
  • Your APIKey must be passed with every method call.
  • There are no usage limits. You can make a method call for each pageview on your site. Caching data is not required or banned.
  • SQL_DATE format=YYYY-MM-DD
  • Each release will have a seperate directory so version updates will not break your site.
  • Any Error in an API call will return an <Error></Error> tag set with an inner <Message> and <Number> tag set.
    • If EventLister.com site load is too high, API requests will be answered with: <Error><Message>Site load too high. Site API Down. Page Aborted.</Message><Number>701</Number></Error>
    • Other possible errors include missing required fields in the you API account.
    • Any <Error></Error> tags and their inner children will ignore your API account settings about \n's, CDATA, etc.
    • An <Error></Error> tag may appear as the root and only element in the XML document or the tag may appear nested as a child within the XML document. The same errors will always appear in the same place, but there are different types of errors and each category is are caught at different points in processing.

API Methods

SiteStatus - Returns info on the EventLister.com site and its API
EventCategories - Lists all categories that we use, their id #, parent id #, name, and pluralized name.
EventDetails - Returns the Full Details of an Event Listing
EventSearch - Returns the Event Listing Search Results for a Given Query
EventAdd - Adds an Event Listing to our main database
EventChainDetails - Returns basic info on the chain and a list of all events in the chain.
EventImage - Returns image of event directly to end user's browser.
EventApplicationImage - Returns image of event application directly to end user's browser.
EventWebsiteForwarder - Forwards the end user's browser directly to event's web site.
MessageSend - Allows other sites to let their users send text messages to Promoter's email addresses on file with us.
MessageCheckStatus - Allows other sites to check on the status of messages sent to promoters.


Method: SiteStatus - Returns info on the EventLister.com site and its API

Description: - Returns info on the EventLister.com site and its API. This method should be called before any other API calls to ensure all is OK. This method should also be called every 5 minutes or so during updates.
Primary Location: http://www.EventLister.com/api/v1/SiteStatus.php
Alternate Location: http://www.EventInterConnect.com/api/v1/SiteStatus.php

Input Variables:
     None
Output Variables:
<SiteStatus>
    <OKToUseAPI>YES or NO</OKToUseAPI> - This is the only important field!
    <LoadLevel>1/10 to 10/10</LoadLevel> - Next most important. At Load 5/10 the API will hard fail with an error message returned. At load 4/10 OKToUseAPI is already returned as NO.
    <AVGLoadTime>float seconds</AVGLoadTime> - Avg time per page load site-wide for last 5 min.
    <PagesRequestedPerMinute>int #</PagesRequestedPerMinute> - # Pages Requested per min.
    <PeopleOnlineNow>int #</PeopleOnlineNow> - Number of Active IPs.
    <UsersOnlineNow>int #</UsersOnlineNow> - Number of Active logged-in registered users.
</SiteStatus>

Usage:

- Normal API usage should be throttled according to our site load. While the site API will self throttle with errors if site load gets to above 4/10, it is best to prevent such a level from even being reached. At load 0/10 you might be able to forget about any self throttling. At Load 1/10 you can still safetly probably call hundreds of API methods per minute. At Load 3/10 you should pull back further. I don't have any really good suggestions yet. This is all sort of preliminary. The EventSearch method is the hardest to generate and of the most concern; one call to it is as hard as hundreds to EventDetails and the site may only respond to one or less per second.
- You can call this method as often as you wish, but OKToUseAPI depends on the LoadLevel which is only calculated site-wide every 60 seconds.

Samples Code:

Sample PHP Code      Sample PHP Code Live Example / Sample Output     
Sample XML Output



Method: EventCategories - Lists all categories that we use, their id #, parent id #, name, and pluralized name.

Description: - Returns an xml list of all current categories used by Event Listings in our main database
Primary Location: http://www.EventLister.com/api/v1/EventCategories.php
Alternate Location: http://www.EventInterConnect.com/api/v1/EventCategories.php

Input Variables:
     None
Samples Code:

Sample PHP Code      Sample PHP Code Live Example / Sample Output     
Sample XML Output



Method: EventDetails - Returns the Full Details of an Event Listing

Description: - Returns the Full Details of an Event Listing from either of our databases: The Main Database that has all the events in it that you see on our site OR the raw Import Data Database from other sites (tourism, coc, venues, etc.)
Primary Location: http://www.EventLister.com/api/v1/EventDetails.php
Alternate Location: http://www.EventInterConnect.com/api/v1/EventDetails.php
Input Variables:
     EventNumber - INTEGER - Returns Event from our Main Database of Approved Listings
OR
ImportedEventListingIDNumber - INTEGER - Returns an event from the import dabatase, it indexes by ImportedEventListingIDNumber, but one field returned for each listing is the 'EventNumber' that we use, if this field is set, it is in our main database. These are NOT APPROVED as accurate!

Samples Code:

Sample PHP Code      Sample PHP Code Live Example / Sample Output     
Start of Sample C# ASP Code     
Sample XML Output



Method: EventSearch - Returns the Event Listing Search Results for a Given Query

Description: Returns the Event Listing Search Results for a Given Query
Primary Location: http://www.EventLister.com/api/v1/EventSearch.php
Alternate Location: http://www.EventInterConnect.com/api/v1/EventSearch.php

Input Variables:
     OutputType - STRING - options are BasicResults (default), FullEventDetails, or Custom. BasicResults returns a few important fields for search results. FullEventDetails is like doing a EventDetails method lookup on the event - it returns everything. Custom allows ysers to define which fields are returned and in which order via the FieldsRequested variable..
     IncludeDeleted - SET_STRINGS - ( YES or TRUE -OR- NO or FALSE ), defaults to NO. NO is usefull for fetching results to display immediately to users; YES is usefull for nightly updates to include which events were deleted.
     FieldsRequested - STRING - Only used if OutputType=Custom! Should contain a comma separated list of fields to be returned for each matching event. You must specify every field you want if OutputType=Custom, even the EventNumber. Possible fields are: EventNumber, MergedIntoEventNumber, ChainID, Status, Canceled, CanceledReason, PrimaryCategory, EventCategories, EventCategoriesRaw, Featured, Highlighted, Paid, Link, PromoterNumber, UserNumber, Name, StartDate, EndDate, DateTrust, PrintableDates, Hours, ApplicationDeadline, DaysLeftToApply, AddressL1, AddressL2, City, State, Zip, PromoterPhone, PromoterContact, AttendanceInt, TypeFlags, Years, Lat, Lon, GeocodeAccuracy ( =1 Lat and Lon accurate to street level, =0 or =-1 if accurate to city level if Lat and Lon are set to non-zero) , TimeAdded, TimeLastUpdated, RatingsTotal, RatingsCount, ShortDescription, Attendance, AttendanceMethod, NumberOfSpaces, NumberOfFoodSpaces, NumberOfRetailSpaces, AdmissionPrice, BoothPrice, FoodBoothPrice, RetailBoothPrice, strJuryFee, JuryCheck, strPastDeadlineFee, JuryReq, Restrooms, Parking, ParkingCost, VendorParking, SetupTime, LocationType, FacilityName, StillAcceptingApplications, Description, Entertainment, Activities, RainDate, RainDateStatus, RainDatePolicy, RainDateNotify, ApplicationRules, RuleFlags, ApplicationQuestions, ResponseDeadline, ApplicationFlags, FirstYear, VendorReturn, ApplicationAcceptance, ApplicationAcceptancePV, WaitList, Directions, WebsiteURLStatus, HasEventScans, EventScans, ImageURLs, AdditionalInfoLinks - all return the tag they are, except the last 3 plural inputs will return 0, 1, or many singulars, i.e. if you have EventScans in the FieldsRequested, you will get an EventScan tag for each scan the event has.
     DisplayNumber - INTEGER - defaults to 100
     StartNumber - INTEGER - defaults to 0
     TotalNumber - INTEGER - defaults to the total number
     KeyWords - STRING - space seperated ANDed keyword
     StartDate - SQL_DATE YYYY-MM-DD - defaults to Today
          or can pass as 3 variables: StartDate_year, StartDate_month, and StartDate_day
     EndDate - SQL_DATE YYYY-MM-DD - defaults to far far away
          or can pass as 3 variables: EndDate_year, EndDate_month, and EndDate_day
     AddedSince - SQL_DATE YYYY-MM-DD - defaults to 0000-00-00
          or can pass as 3 variables: AddedSince, AddedSince_month, and AddedSince_day
     UpdatedSince - SQL_DATE YYYY-MM-DD - defaults to 0000-00-00
          OR   pass as 3 variables: UpdatedSince_year, UpdatedSince_month, and UpdatedSince_day
          OR   pass as integer unix timestamp as variable name UpdatedSinceTime
     UpdatedSinceTime - INT UNIX TIMESTAMP - defaults to 0

     SearchLocationMethod - SET_STRINGS - ( Zip, CityState, CountryRegion, EventNumber ) - defaults to everywhere
          'Zip' Option - Seaches a specified radius around a zip code
               Radius - INTEGER - search radius in miles
               Zip - STRING - 5 Digit US zip codes only right now
          'CityState' Option - Seaches a specified radius around a city, state
               Radius - INTEGER - search radius in miles
               City - STRING - US City name
               State - STRING - US 2 digit state abreviation
               CityState - STRING - 'City, ST' format or 'City,ST'
          'CountryRegion' Option - Seaches an entire country or region (states in the US)
               Radius - INTEGER - search radius in miles
               Country - STRING - Country name
               Region - STRING - Region/State name
               CountryRegion - STRING - 'Country, Region' or 'Country,Region'
          'EventNumber' Option - returns a specific event.
               EventNumber - INTEGER - event number to return. All other variables ignored!
     RequirePicture - Y or unset
     OnlyIndoor - Y or unset
     OnlyOutdoor - Y or unset
     OnlyJuried - Y or unset
     OnlyNonJuried - Y or unset
     OnlyRetailAllowed - Y or unset
     OnlyFoodAllowed - Y or unset

Description: This method is set up to automatically handle pageing of the search results for you. It defaults to returning only page at a time. The results include a TotalNumber variable, indicating the total number of results available for subsequent method calls. Each call accepts a StartNumber and DisplayNumber variable to identify the results to return.

Samples Code:

Sample PHP Code      Sample PHP Code Live Example / Sample Output     
Sample XML Output



Method: EventAdd - Adds an Event Listing to our main database

Description: - Adds an Event Listing to our main database
Primary Location: http://www.EventLister.com/api/v1/EventAdd.php
Alternate Location: http://www.EventInterConnect.com/api/v1/EventAdd.php

NOT SURE IT WORKING YET! - Feedback requested on design! Method is implemented but not completely tested. Please give feedback. It is finished, but NOT Tested in bulk by any user yet!!! Only add a few events until we verifty this is working. :

There are many possible fields to be passed; a few are required but most are optional. Because there is the potential for the data that needs to be passed in to be greater then the max URL length (2k?), you probably will need to use a HTML form POST for this method instead of appending the variables onto at the end of the API method's base URL using a '?'; although that method will work fine for the most basic event to be added.

Events Listings that are added with this method do NOT go live on our site immediatly, they must be approved. This is to ensure that no other API user or site user will see any imported event listings before we look them over.


Input Variables:

YourEventIdentifier REQUIRED - string (used to complete the EventIdentifier details URL you provided - api settings)


PriorEventNumber SUGGESTED - integer
  or (Either our EventNumber for a Prior listing of this event or our EventChainID is SUGGESTED)
EventChainID SUGGESTED - integer


PromoterUserNumber SUGGESTED - integer
  or PromoterNumber SUGGESTED - integer
  or (one of these top two or the below phone or email is REQUIRED)
PromoterContactName SUGGESTED - string
PromoterCompanyName SUGGESTED - string
PromoterPhone SUGGESTED - string (xxx-xxx-xxxx)
PromoterEmail SUGGESTED - string
PromoterWebsiteURL SUGGESTED - string


EventName REQUIRED - string
EndDate REQUIRED - sql date (YYYY-MM-DD)
StartDate REQUIRED - sql date (YYYY-MM-DD)
ApplicationDeadline - sql date (YYYY-MM-DD)
DateTrust REQUIRED - ('', 'APPROXIMATE', 'CONFIRMED')
VendorEvent REQUIRED - ('', 'YES', 'NO')
CanShow SUGGESTED - ('', 'YES', 'NO')
LikelyToRepeat SUGGESTED - ('', 'YES', 'NO')
NotReoccuring SUGGESTED - ('', 'YES', 'NO')
Canceled - ('', 'YES', 'NO')
CanceledReason - string
AddressL1 SUGGESTED - string
AddressL2 SUGGESTED - string
City REQUIRED - string
State REQUIRED - string
Zip REQUIRED - string
Country (default: US) - string
EventCategories SUGGESTED - string (comma seperated list of our category numbers)
WebsiteURL SUGGESTED - string
Description SUGGESTED - string - no limit
Entertainment - string - no limit
Activities - string - no limit
Attendance SUGGESTED - string
AttendanceInt - integer
AttendanceMethod - ('', 'EAnticipated', 'PTickets', 'ATickets', 'AGate', 'EGate', 'ECrowd', 'ACrowd', 'EPolice', 'APolice')
NumberOfSpaces SUGGESTED - integer
AdmissionPrice SUGGESTED - string
YearsInProduction SUGGESTED - integer
BoothPrice - string
FoodBoothPrice - string
NumberOfSpacesLY- integer
strJuryFee - string
NumberOfFoodSpaces - integer
NumberOfFoodSpacesLY - integer
Commission - string
SetupTime SUGGESTED - string
Hours SUGGESTED - string
LocationType - string
Awards - string
Parking - string
Restrooms - string
Advertising - string
TablesChairs - string
NumberOfSpacesLeft - integer
NumberOfFoodSpacesLeft - integer
StillAcceptingApplications - ('', 'YES', 'NO')
strPastDeadlineFee - string
Electricity - string
Water - string
ApplicationRules - string
RVParking - string
VendorParking - string
JuryReq - string
CrafterAppURL - string
FoodAppURL - string
VendorBreakfast - string
VendorLunch - string
VendorHelp - string
HaulDetails - string
NumberOfRetailSpaces - integer
NumberOfRetailSpacesLeft - integer
RetailBoothPrice - string
RetailAppURL - string
ParkingCost - string
Insurance - string
TypeFlags - string
RuleFlags - string
StillNeeded - string
NotNeeded - string
QualityFlags - string
QualityLevel - string
CityPermitPhone - string (xxx-xxx-xxxx)
ImageURLLogo - string
ImageURL1 - string
ImageURL2 - string
ImageURL3 - string
ImageURL4 - string
ImageURL5 - string
ImageURL6 - string


Output Variables:

AssignedEventNumber - This will be an integer number used for your subsequent API requests referrign to this listing. This is also the same EventNumber that we will return with EventSearch method calls and that EventDetails takes in as input.
PromoterNumber - The new assigned one, or ther passed in one returned.
UserNumber - The new one assigned, a 0 if none was, or the value of PromoterUserNumber passed in if it was.


As we approve your imported event listings, we may assign them to existing event chains or we may find that we already have the event listing listed, in which case one of the 2 will be deleted and marked as merged into the other. To capture these various changes, you should do an EventDetails method on the 'AssignedEventNumber' a few days after you add it. You can poll for updates nightly or more often; the Event's 'Status' will be returned as 'APIImportHold' until we approve it or mark it as deleted, then either 'DELETED' or '' (empty status is an OK status). When we approve or reject the listing, it's LastUpdated time will be refreshed so it should even be picked up in your normal updates, but as an event listing you inserted it is a special case & it should be handeled as such.

Sample Code:

     Live Example Code w/ Sample XML Output      The Sample PHP Code


Method: EventChainDetails - Returns basic info on the chain and a list of all events in the chain.

Description: - Returns basic info on the chain and a list of all events in the chain.
Primary Location: http://www.EventLister.com/api/v1/EventChainDetails.php
Alternate Location: http://www.EventInterConnect.com/api/v1/EventChainDetails.php

Should be working.. Untested..

Input Variables: - ALL required!
     ChainID - int - the ChainID value returned from EventDetails or EventSearch.


Output Variables:
     ChainID - int - the same one passed as input
     PromoterNumber - int the PromoterNumber for the chain
     EventName - string - the Name of the Event (one of...)
     NameVariations - string - a seperated list of all possible event names
     NotReoccuring - ENUM('','YES','NO') - Blank equates to NO
     Event - There will be an Event tag for EACH event in the chain. Each with the fields:
         EventNumber - int - the EventNumber referencer
         StartDate, EndDate - SQL Dates - The dates of the event
         Status - ENUM('','DELETED') - The Satus uf the event, same as the Status field from an EventDetails or EventSearch for the EventNumber.



Method: EventImage - Returns image of event directly to end user's browser.

Description: - This method is not to be Pre-Run or it's output cached. The method URL is what you will direct end user's browsers to as the <IMG> src= attribute. It will then return the image of event directly to user's browser as an embedded image.
Primary Location: http://www.EventLister.com/api/v1/EventImage.php
Alternate Location: http://www.EventInterConnect.com/api/v1/EventImage.php

To be added soon!

Method: EventApplicationImage - Returns image of event application directly to end user's browser.

Description: - This method is not to be Pre-Run or it's output cached. The method URL is what you will direct end user's browsers to as the <IMG> src= attribute. It will then return the image of event application directly to user's browser as an embedded image.
Primary Location: http://www.EventLister.com/api/v1/EventApplicationImage.php
Location: http://www.EventInterConnect.com/api/v1/EventApplicationImage.php

To be added soon!

Method: EventWebsiteForwarder - Forwards the end user's browser directly to event's web site.

Description: - This method is not to be Pre-Run or it's output cached. The method URL is what you will direct end user's browsers to as the href attribute in an <A> tag. It instantly forwards the user's browser directly to event's web site, your choice of same window or a new one if you use add a target=_blank attribute to your A tag.
Primary Location: http://www.EventLister.com/api/v1/EventWebsiteForwarder.php
Alternate Location: http://www.EventInterConnect.com/api/v1/EventWebsiteForwarder.php

To be added soon!

Method: MessageSend - Allows other sites to let their users send text messages to Promoter's email addresses on file with us.

Description: - Allows other sites to let their users send text messages to Promoter's email addresses on file with us. Your users fill out a form on your site, then your site calls this method to 'deliver' the message. Messages are delivered by email and to the promoters online EventLister.com message/mail interface.
Primary Location: http://www.EventLister.com/api/v1/MessageSend.php
Alternate Location: http://www.EventInterConnect.com/api/v1/MessageSend.php


Input Variables: - ALL required!
     RecipientPromoterNumber - int          OR      RecipientUserNumber - int
     Subject - string
     HTMLMessageBody - string
     FromEmail - string
     FromName - string
     FromIP - string ###.###.###.###

Output Variables:
     MessageIdentifier - int
     RecipientUserNumber - int


Details:
  • This method will only succesfully work on PromoterNumbers that have an email on file with us; else an error is returned. Events who's promoters have emails on file with us now have a non-zero <UserNumber> returned.
  • This method will send a message to any UserNumber, but at present is only intended for contact of Promoters by people inquiring about their listings. In the future, the API will be extended to allow for further intergration and connectivity between sites, but as that is yet undefined there is for now NO reason for any of your code to send messages to any but our promoters. Violators banned.
  • The message will always be delivered to the Recipient as an email to their email address on file and as being 'from' your inputted FromEmail and FromName.
  • The message that is sent is also added to the Recipients EventLister.com online mailbox. If the FromEmail is also registered with EventLister.com, then the promoter's online mailbox shows the message as From the appropriate user account, otherwise the message is listed as being from your inputted FromEmail.
  • Just so it's said explicitly: Your supplied FromIP, FromEmail, and FromName will not be used by EventLister.com in any way other than to deliver your message and tracking to block pattern-identifiable spamming; the supplied values for the FromEmail and FromName inputs will not be stored anywhere in our database except our Messages table (therein the FromEmail and FromName will be stored in one row along with your HTMLMessageBody and Subject and only accessable to the message recipient) and our MessageTracking table which stores the IP and other fields for limiting spam/auto-senders and to ensure accountability tracking for all messages sent through us. We suggest you retain similar records of sent mail.
  • You are required to implement basic spam-prevention and automatic-scripts' use of YOUR website and web-forms before attempting to send messages to our registered users. Any messages sent using the SendMessage API method must be: sent by registered users of your site, Captcha of similarly code-protected at least per account preferably per each message, rate limited internally in your software as to your own limits [for example 3 emails/5 minutes and 30/day] for each of your users. - ALL API USERS MUST IMPLEMENT !
  • The ONLY allowed use of this method is to relay messages from your site's users to the recipient whom we hold the contact email of. You may not send your own or site-orientated messages to our users - if you have a particular need, please ask. EventLister.com already sends all sorts of email updates to users:
    • All users get a weekly emailed listing of shows, with promoters also receiving an update on their upcoming listings or reminders to add listings.
    • Promoters get emails almost monthly specifically asking them to add event listings if we currently have none for them.
    • Promoters with upcoming but incomplete listings get special emails almost monthly alerting them to the missing fields.
    • Promoters are also sent helpfull emails as their dates approach (90, 45, & 15 days in advance) with info on topics such as advertising ideas, finding exhibitors, tips on confirmation packets, etc.
    • Sadly, many promoters just dont care to complete their listings or don't have time or don't do the online thing that well and want to but think they can't so don't.

Samples Code:

Sample PHP Code      Sample PHP Code Live Example / Sample Output     


Method: MessageCheckStatus - Allows other sites to check on the status of messages sent to promoters.

Description: - Allows other sites to check on the status of messages sent to promoters. This function takes as input the MessageNumber from a previous MessageSend method call. It returns only whether or not the message was known to be opened (presumed read). The message is presumed unread unless it was either clicked on and read online (alsways known) or if their e-mail client software opened the message and asked our webservers for an embedded tracking image that determines if the message was read.
Primary Location: http://www.EventLister.com/api/v1/MessageCheckStatus.php
Alternate Location: http://www.EventInterConnect.com/api/v1/MessageCheckStatus.php

NOT SURE IT WORKING YET! - Feedback requested on design! Method is fully implemented but untested except minimaly. Please give feedback.
Input Variables: - ALL required!
     MessageIdentifier - int

Output Variables:
     MessageIdentifier - int
     ReadStatus - ENUM('UNKNOWN','READ')
     DeletedStatus - ENUM('NORMAL-UNDELETED','DELETED-USER','DELETED-SYSTEM','DELETED-USER-SYSTEM')
     RecipientUserNumber - int
     FromUserNumber - int
     SendTime - int

Your 'FromEmail, FromName, and FromIP' are on file but not retreivable through the API for your user's security.


Details:
  • This method will only succesfully work on MessageIdentifier that the API has returned to you as the result of MessageSend calls.
  • ReadStatus values explained: 'UNKNOWN'-the user did not read the message online or in an email client that opened that embeded read-tracking image; 'READ'-the use did open the message)
  • DeletedStatus values explainted: 'NORMAL-UNDELETED'-in their inbox; 'DELETED-USER'-user has deleted the message online; 'DELETED-SYSTEM'-we have purged the mail during routine db maintenace from their online message inbox w/o their deleting it, 'DELETED-USER-SYSTEM'-the user had deleted the message and we later also purged the message during routine db maintenace.)

Samples Code:

Sample PHP Code      Sample PHP Code Live Example / Sample Output     





Version Changes from v0.1b to v1
Current Version: v1 documentation (this page) - released 11/2008
Previous Version: v0.1b documentation

  • New Methods:
    • EventCategories - spits out a lookup list of ALL our category codes to names in tree form.
    • MessageSend - allows emails to be sent to our promoters.
    • MessageCheckStatus - allows checkign of status of sent emails.
    • SiteStatus - used to determine if API usage is OK. - ALL API USERS MUST IMPLEMENT !
    • EventAdd - allows API users to ADD event listings to our database for further syndication through our network.
  • EventDetails & EventSearch Method - New output variable <DateTrust> tag to add support for @ Approximate Only events. - ALL API USERS MUST IMPLEMENT ! THE API USAGE LISENCE REQUIRES THAT YOU SHOW EVERYWHERE THAT A LISTING IS APPROXIMATE, if it is so marked with us, unless you HAVE confirmed the date!! This includes any: 'PREVIEW MODE', SEARCH RESULTS, EMAILED RESULTS, Listing Summary, Actual Details Page, ETC, ETC. You must say on the event's details page that the date is 'Approximate Only' in colored text, near the date. You must use in search results at minimum a symbol or icon that is colored, near the date, and that links to a key/legend explaning the symbol means an event's date is 'Approximate Only'. Here, we use a @ that links to an explination of the red @. If you display ONE of our approximate-marked listings without indication that it IS only approximate/unconfirmed, you wil be assumed to be intentionally portraying inaccurate information as accurate in an attempt to force/garner more user signups, and will be banned from API use.
  • EventSearch Method - New input variable OutputType. Defaults to previous standard search results containing a few major fields, but now a second option allows the full details to be returned with an single EventSearch method call instead of one EventSearch and many EventDetails method calls for each match. All nightly or periodic updates must use OutputType=FullEventDetails instead of many EventDetails calls! - ALL API USERS MUST IMPLEMENT !
  • EventDetails Method - Because of new option EventSearch.OutputType=FullEventDetails, EventDetails method should now not be called many times to get the details on many events. It almost should not be used now unless your implementation is NOT caching our data and you have a user requesting to view the full details of an event or something similar. - ALL API USERS MUST IMPLEMENT !
  • User Account setting for CDATA encasing or not on all fields.
  • Bug Fix- EventDetails output field TimeLastUpdated is now reset by all site actions that affect any field within added to or edited by any means. It is also now reset by the 'Deleting' and 'Undeleting' of events on our site. Before this change, some events were updated in various ways did NOT have TimeLastUpdated reset on them, and so searches for only events that were recently updated would NOT have returned them when it should have as it now does.
  • EventDetails & EventSearch Method - New output variables:
    • <MergedIntoEventNumber> - Status=Deleted events may now return a field of <MergedIntoEventNumber> if it WAS merged into another, with the value being our EventNumber of the final listing. Event 1190866 is such a deleted & merged event.
    • <ChainID> - INT - our EventChainNumber for the event through the years.
    • <UserNumber> - INT - our UserNumber for the Promoter (only set if we have an email for them). A UserNumber signals the successfull possiible use of the MessageSend method to contact this promoter.
    • <WebsiteURLStatus> - ENUM('ON-FILE') - Right now, this fields is only returned if we have a website URL for the event, and then it is set to the sting: ON-FILE. ON-FILE signals the successfull possible use of the EventWebsiteForwarder method for this EventNumber. There may be other possible values in the future.
    • <HasEventScans> - ENUM('','YES') - YES indicates there are scanned applications available for this event.
    • <EventScans> - If HasEventScans=YES, then There will be a series of <EventScan> tags within a <EventScans> tag.
      • <EventScan>
        • <ID> - int - indentifier for the scan document
        • <Page> - int - page # for ordering
        • <Size> - int - size of full size image in bytes
        • <TimeAdded> - int - time added in unix timestamp
        </EventScan>
      • <EventScan> - one EventScan for each scan document for the listing.
        ....
        </EventScan>
      </EventScans>
  • EventSearch Method - new OutyputType=Custom and new input variable FieldsRequested that determines the fields returned for OutputType=Custom.



  • Questions Asked
    I noticed that for some records there is missing details. However, some of the information appears to be there on past listings linked by ChainID. Is this correct?
    Would an alternate solution be to download the archived/old events and match them via ChainID to the new events in question?
    What is the status of the FullEventDetails method and future support?
    Regarding updates, do you prefer that data is paged in chunks or can the user stream it all at once?
    Is there a preferred time-of-day?, or just at 'night' that updates should be completed?


    Question: I noticed that for some records there is missing details. However, some of the information appears to be there on past listings linked by ChainID. Is this correct?
    Yes. I do have many events that are known to be the same event different year, and where there later years have less info. I was planning to address it with a sort of approval import system as the date confirmer or the 'Add Events by Last Year Copy' one. This is not yet being done in any way.

    Question: Would an alternate solution be to download the archived/old events and match them via ChainID to the new events in question?
    You certainly could; in which case you don't even need another table yet if your event table has a ChainID column. The EventChain table and returned data only has in it info like 'event will continue or not', the promoter #, the event name variations, etc. The EventChain method will spit back the list of events in the chain too, but we don't store that list of events in the EventChain table or anywhere, we use the relation to the Event table ChainID column.

    Question: What is the status of the FullEventDetails method and future support?
    It works fine and will continue to. It can be used for anything except bulk update calls. It's meant more for some anticipated API user sites that will not be caching the data and so will need to call it each time an event is viewed on their site, which is acceptable, correct usage. The EventSearch method certainly can now do anything that FullEventDetails can plus more, but it will remain in the API to simplify usage.

    Question: Regarding updates, do you prefer that data is paged in chunks or can the user stream it all at once?
    I'm leery on streaming, only for fact of errors in progress will be hard to recover from and then you must start all over or now develop a 'pull the rest' script... the overhead on an http page call is small; however, as pages get larger and the strings we are processing do, they take longer to do all the str_ functions on and so beat both our CPUs. So since this is chunkable data, my gut after this exploration tells be chunks, but medium ones. 100 events? All of our site pages, API included, have 30 second execution time limits. So if it takes our webserver more than 30 seconds to assemble your result page, it will be truncated short. (The EventSearch method has an extended limit of 220 seconds.) Users can try doing their even searches with very high limits on the numbers of events returned per page so that only one large EventSearch call returns thousands of events and let me know what happens.

    Question: Is there a preferred time-of-day?, or just at 'night' that updates should be completed?
    For now, you can do at any time if you follow the SiteStatus method's OK. I'll build in a throttler eventually so the API answers slower if it needs the rate slowed, so it can auto throttle as needed. Right now, there is a site-wide one that effects the LoadLevel.









♫♫
report a Typo or Error on this page         (c) Louis Marquette - Legalese - About Site - Site Map                   Desigh by Louy of Devity.com