Application Programming Interface for Complete Obituaries

The Complete Obituaries system uses a custom XML format to import data into its database. This XML file should be placed on a public location on your web server; we recommend naming the file obituaries.xml and placing it on the public root of your site, but if necessary, a different path can be arranged upon setting up your account with the system. The file format and a sample XML file are given below; programming examples in common languages can be accessed using the links to the left.

XML File Format

The obituaries XML file needs to be a valid, well-formed XML document, and should be in UFT-8 encoding; other characters sets are not guaranteed to display correctly when imported into the database. The root XML tag should be named obituaries, and should have a generated attribute containing the timestamp of the last file generation. The importer uses this timestamp to determine whether any updates have been made to the file:

<obituaries generated="2014-09-16 02:24:48">

Tag names are case-sensitive. The date can be given in any reasonably valid date format, but should include the full date and time stamp of the last file generation.

Obituary Tags

Each obituary entry must contain at minimum an ID unique to the file and a first and last name. Several additional fields, explained below, help to fill out the obituary entry. Tags are case-sensitive, but may be given in any order. All data must be properly escaped for XML; this includes any HTML formatting in the longer text fields. The following table outlines each field and its usage:

Tag Required Length Description
<uniqID> Yes 10 Unique identifier for this obituary; must be unique within the file. Typically, this will be the database ID, but can be any alphanumeric string up to 10 characters in length.
<firstName> Yes 50 Person's first name, up to 50 characters in length; required field.
<lastName> Yes 50 Person's last name, up to 50 characters in length; required field.
<middleInitial> No 50 Person's middle name or initial, up to 50 characters.
<birthDate> No Person's date of birth, in any valid date format. This field is optional, and not presently used, but may be included in the future.
<deathDate> No Person's date of passing, in any valid date format. Although this field is not technically required, it is highly recommended, as the search functions make use of this date for sorting and filtering.
<city> No 100 City of origin or of the person's last place of residence; used in search filtering.
<state> No 2 State of origin or of last residence; used in search filtering. Two-letter abbreviation preferred.
<bio> No Biographical information; can be given in HTML or plain text, but be sure to escape any HTML tags. Paragraphs, line breaks, bold, and italic will be preserved; other tags or styling will be stripped for the purposes of consistency within the entries.
<visitation> No Information regarding visitation services; can also be in HTML format, with the same stipulations as the bio.
<service> No Information regarding religious or other funerary services; can also be in HTML format, with the same stipulations as the bio.
<photo> No Path to the person's photo; only one photo may be attached per obituary, and the full path, including the http://, must be included. Images will be resized automatically as necessary. Please specify only JPEGs, PNGs, or GIFs; other formats are not supported.
<link> No 200 Full URL to the obituary details on your site. This link will be included on the search details page to provide a backlink to your site.

Sample File

Below is a sample XML file with two obituaries: The first includes every valid field, and the second includes the recommended minimum.

<?xml version="1.0" encoding="UTF-8"?>
<obituaries generated="2014-09-16 02:24:48">
    <obit>
        <uniqID>1</uniqID>
        <firstName>John</firstName>
        <lastName>Doe</lastName>
        <middleInitial>Q</middleInitial>
        <birthDate>5/10/1930</birthDate>
        <deathDate>9/16/2014</deathDate>
        <city>Eau Claire</city>
        <state>WI</state>
        <bio>&lt;p&gt;This is a test obituary. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
            incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
            nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
            dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt
            mollit anim id est laborum.&lt;/p&gt;</bio>
        <visitation>Visitation will be at Complete Obits Funeral Home on &lt;strong&gt;Friday, September 19, 2014 at 5pm.&lt;/strong&gt;</visitation>
        <service>Services will be held at St. John's Church this Saturday at 1pm.</service>
        <photo>http://site.com/images/obituaries/john-q-doe.jpg</photo>
        <link>http://site.com/obituaries/John-Q-Doe</link>
    </obit>
    <obit>
        <uniqID>2</uniqID>
        <firstName>Anne</firstName>
        <lastName>Jenkins</lastName>
        <middleInitial>D</middleInitial>
        <deathDate>September 13th, 2014</deathDate>
        <bio>This is a test obituary. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
            incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
            nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
            dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt
            mollit anim id est laborum.</bio>
    </obit>
</obituaries>

Note: It is not necessary to wrap fields; the file here has been wrapped to fit better in the display. The XML importer converts line breaks within non-HTML text to <br /> tags automatically, which may cause text to break strangely if the source code is word-wrapped.

Common Problems

Bad or missing generated date

The date and time format in the generated attribute should include a full date and time stamp; if this date is missing or cannot parse, the feed may be ignored as unchanged. If you're having problems with the feed being read and the XML is fully well-formed, try changing the date format to standard SQL format: 2014-09-16 02:24:48.

Special XML characters not escaped

In XML, certain characters (< > & ' ") have special meaning, and may be mistaken as tags or entities. Because XML is much stricter than HTML, failing to escape these characters may prevent the file from parsing. The most common issue is with ampersands & in plain text and with HTML tags in rich text.

Use the following entities to escape these characters in your text:

Character Name Entity
& Ampersand &amp;
< Less-than &lt;
> Greater-than &gt;
' Single-quote &apos;
" Double-quote &quot;

Using entities from HTML

Unlike HTML, XML supports only five named entities, as listed above. All other entities must be given using their numeric reference codes; for example, the copyright symbol (©) can be specified as &#xA9;.