The XML FAQ is broken into three sections: General XML questions about our structure, DTDs, and schema, flat file guide provisioning, our XML feed generation system, and specific sections for core Event and Event highlight feeds

General XML Questions

Q: Can I get the flat-file city guides, resort guides, and other editorial fed dynamically from your servers?
A: No; these type of guides can only be provided through flat-file delivery. It is not currently possible for us to host this content in database form alongside our event content - live content delivery to city, resort, and other guides is limited to Event feeds at this point in time.
Q: Can I get the event guides in flat-file form?
A: No; event guides are only available through the HTTP feed system from our live application. Each customer has bespoke requirements on what parts of the world they want to purchase; the application manages a customer's view of the world and ensures that the most up to date view of that content is available at all times.
Q: How do I ensure good performance of the XML?
A: Ensure that you have implemented the required EntityHandler/DTDHandler interfaces to your SAX/DOM parser, and provided appropriately-set-up XML readers to your XSLT processing; failure to do so will result in multiple requests to the internet for each parser operation as the parser attempts to resolve DTD, schema, and entity references contained in the XML. More information on using DTD and EntityHandler interfaces will be in your parser documentation.
Alternately, you can use a standard XCatalog implementation to provide a mapping to your XML parser of entity references it discovers and match them to local copies of those documents. More information on using XCatalog will be in your parser's documentation.
If you cannot implement either of the two, or are unsure of your application, copy the DTD references to your local machine, modify the WhatsOnWhen DTD to reference the local W3C entity files, and modify each XML document to reference the newly modified (and local) WhatsOnWhen DTD which you have updated to reference those files. This ensures that both the WhatsOnWhen guide DTD, as well as the ISO-8859-1 entity files it refers to, are available locally.
Q: I've turned validation off, but it's still requesting access to the DTD. Why?
A: There are two parts to XML parsing - a validation pass which ensures that the content of the XML is valid, and a 'delivery' pass which actually delivers the content through the parser API. While some implementations may grey the line between the two passes, the logical division remains true. A validation pass can be disabled - but in order to process an entity(let's say an "&" - encoded as "&" in an XML document) it needs to find that entity's definition. For ISO-LATIN-1 entities for western languages, these are encoded in the DTD and entity references; the parser must always parse all foreign entity references in order to ensure that it can translate the "&" into a "&". This pass can't be turned off - that's why EntityHandlers/DTDHandlers or an XCatalog implementation (or modifying source documents, for that matter) is required.
For more information, see our Implementation Guide on XML Parser Requirements for more detailed instructions.

Event XML Feeds

Q: How are these feeds generated?
A: The feeds are generated direct from our core content management database; they utilise the same internal mechanisms as those which are used to generate our hosted sites and cobrands, and are being made available for third parties to easily integrate our core content into their service offerings.
Our internal system uses a java-based infrastructure, whereby a JDBC-compliant database is called by our JDO (Java Data Objects) implementation to load database information into Java objects representing our internal schema; those objects are then XML serialise4d using the same JDO implementation directly into an HTTP response to clients.
Castor provides all of our internal JDO functionality; mapping files provide the bi-directional transformations from XML->Java->DB and from DB->Java->XML.
Q: How can I process these feeds?
A: A variety of basic mechanisms exist. You may, like us, use a data objects framework to provide object-relational mapping to XML. XML Schema code generators can generate source code for objects which can read/write a given XML format by parsing a schema and generating code objects for your preferred programming languages. In addition, you can use XML content directly via XSLT, storing individual articles in XML format and doing postprocessing via XSLTs to generate specific page fragments for static inclusion.
Q: What are the restrictions on feed access?
A: Before you can be granted access to our feeds, you must supply us with all of the IP addresses that will be used to access the service; those IP addresses will be entered as restrictions to ensure that your account cannot be abused by others, or our content 'lifted' without our permission.
In general, customers are not granted the right to sell on our content to third parties - it is important that our feeds be as protected on our own feed provider as they are on your internal systems. Unless you have specifically contracted for the ability to sell on our feeds, please do not do so.
In addition, there are issues of parallelism to consider: Feeds are restricted to three simultaneous requests, per server, per customer, per feed type. In addition, there is a global restriction pool, an upper bound on the number of simultaneous requests which are permitted for a specific feed type; this is nine concurrent requests, per server, per feed type. On the live system, that's almost 30 permitted simultaneous requests; other requests will queue and be dealt with as worker threads are freed from serving other requests.
As there is a single server in staging, staging is a highly restrictive environment. Moreover, staging is our primary testing server for testing customer content, QA builds before ship, and the like. No guarantees are made as to the uptime or availability of the staging server; please ensure you do not use it in your live service.
Q: What limitations apply to the core XML feeds?
A: Complete feeds should be requested no more often than once per month. For customers who are purchasing small subsets of our core system (specific locations and regions, or specific event rank limitations, or even specific categories) can get away with doing so more often; but for the most part, there is no need to do so.
Record the exact date and time of your last successful parse; you may then feed that same date/time back to us when you are retrieving the feed to receive only the incremental changes made from that date and time. Should your parse fail for any reason, you may re-try that same date/time until that feed is successful; should you have persistent errors or concerns about the data you are receiving, you should contact us immediately through tech@whatsonwhen.com to ensure that it gets looked at ASAP.
Q: How can I request data for a specific location?
A: Locations in our system come in two forms: their native, WOW-internal location ID, and external mapped forms for a variety of standards which we transparently connect internally to a location ID of the appropriate level and location.
Our system is very flexible; we can add any mappings for any namespaces you choose, and even add them for your own internal hotel, area, location, or other reference identities, so long as one entry name is unique to a specific request and area.
We currently include standard mappings for a large number of ISO-3166 2-letter country codes, ICAO weather stations, world weather observation locations, IATA airport codes, and others.
Q: How often should I request an update/incremental feed?
A: Update feeds should be requested no more than once per day; if the normal day's processing fails, you are free to ask as often as once every four to six hours until the processing succeeds.
Q: What times are best for making feed requests of your system?
A: So happy you asked. ;) Our peak operational times begin at roughly 6PM GMT, and go on through the night until roughly 4 AM GMT. The hours of 2-4 AM, when we do legacy feed processing (which we will be required to generate for some time in the future) are to be especially avoided, if possible. However, there are no actual restrictions on your accounts.
Q: When is the best time to make a request for a complete feed?
A: Weekends are our lowest usage time. Saturdays and Sundays are immensely more quiet than weekday traffic - primarily because the greatest load on our system is not from our clients' sites, but from our editorial staff's daily workload of editing, marking up, modifying, and authoring content.

XML Highlight Feeds

XML highlight feeds are of a fundamentally different nature than our core content feeds.

Core content feeds are designed to be purchased by those wishing to take large sections of our content and merge that into their existing offering. As such, we make as much information available as possible in each article, and do our best to ensure the fastest possible operation without incurring high delivery cost of that vast amount of content.

Highlight feeds, on the other hand, are a packaging of some of our own search and highlight logic in a way that is lightweight and fast to implement for customers; a single request returns just enough teaser data to provide on their pages without requiring the customer to implement everything behind the complete implementation; this provides a cheaper way of deeply integrating content into customer sites at a lower development cost than a complete feed implementation.

The following are a few common questions we get asked about the capabilities of our XML highlight feeds:

Q: What limitations apply to the XML highlights feed?
A: XML highlights are subject to the standard restrictions of feeds mentioned above, and those stated within your contract - including locations, categories, and event ranks purchased within that contract.
Q: How much event information is available in a highlights feed?
A: Generally, just the core information - an image if available, date information, and the core text (summary, display name of the event location, and a displayable representation of the nearest 'current' date).
XML highlights also have a maximum record count they will return; that number is currently a maximum of 25.
Q: How often can I request data from a highlight feed?
A: As with all XML feeds, there are access restrictions, as mentioned in the previous section. However, clients of this service, specifically, are expected to cache results for use within a 24 hour period. While our own system will aggressively cache this data, we do prefer that customers police their own use of our service and ensure that site traffic on what is, fundamentally, intended to be a low-cost service to our customers does not exceed reasonable bandwidth and CPU usage. While no bandwidth limiter currently applies to XML feed accounts, abuse by any one customer could lead to such imposition.

Retrieving and Managing Images

How can I retrieve images for events or guides?
Images are retrieved from different places, depending on which feed you are taking. For more information, see the XML Implementation Guide in the XML section on the use of maps and images.
Is there anything I need to know about the use of these images?
All of our images contain caption, copyright, and credits information where appropriate. Whenever any of this information is present, it must be included in the alt tag for that image in order to comply with copyright law. Please make sure you implement credits and copyright in alt text.