Search API for Developers (Beta)

Welcome

The Georgia Log Cabin site contains more than 700 pages of news stories, press releases, and other general information pages from as far back as 1995. We want to make this valuable resource available to the development and research community, so we released search APIs for you. (More of Log Cabin's offline history is available at the University of Minnesota's Tretter Collection.)

In addition to advanced search options like wildcard support, our search engine can output results in several formats including RSS, XML, JSON and others. We are currently testing the nine different output formats described below, and have plans to offer more in the future. These formats make it easy to use our results with JavaScript, Python, PHP, Ruby, Perl, Adobe ActionScript for Flash, Java, C#, C, C++, .NET and other programming or scripting languages.

Please send any suggestions or feedback you have to search@GeorgiaLogCabin.org.

Try It

Feel free to test our output formats here. You do not need an API key to use these services (but please be nice – don't hammer our poor little Perl search engine too hard.)

Documentation

Here's how our search works. Our webmaster is not a real developer, and most sections ask for feedback. Please send any suggestions you have to search@GeorgiaLogCabin.org.

REST Query

Example REST request format:

All values (except for query) are optional. If an optional value is not specified, a default (described below) will be used. Only query is case sensitive.

http://www.GeorgiaLogCabin.org/cgi-bin/search.pl

Service location

query

[string] Search term(s) (required)
This can be any URL-escaped string. Any special characters (except for wildcards and quotes) will be removed. We also use an extensive list of stop words (words we ignore) like the, of, to, a, in, etc. If your query only contains stop words, it will be considered an empty query and an error may be returned (see the sections on Errors below).

require

[all|any] Require any or all of the query words to appear (optional, not case sensitive)
all: conjunctive search (AND), all terms must appear (default)
any: disjunctive search (OR), any term may appear

mode

[standard|brief] How much information to return, only applies to HTML and HTM outputs (optional, not case sensitive)
standard: for title, URL, summary, and date (default)
brief: for title and URL

start

[int] Offset of first result for pagination, first result is 1 (optional, defaults to 1)

rows

[int] Number of results for pagination (optional, defaults to 10)

from

[yyyy-mm-dd] Limit the earliest result to yyyy-mm-dd, yyyy-mm, or yyyy (optional, defaults to any date)
If both from and to are specified, but from is greater than to, the values are automatically swapped.

to

[yyyy-mm-dd] Limit the most recent result to yyyy-mm-dd, yyyy-mm, or yyyy (optional, defaults to any date)
If both from and to are specified, but from is greater than to, the values are automatically swapped.

sort

[relevance|newest] Sort results by (optional)
relevance: sort descending by relevance (most relevant pages first, default)
newest: sort descending by page publish or update date (newest pages first)

output

[html|htm|rss|xml|json|csv|tsv] Data format for results (optional, not case sensitive)
html: Full HTML page in Georgia Log Cabin site format (default)
htm: Bare HTML for use in frames or iFrames.
rss: RSS for news readers.
xml: XML for web applications or AJAX.
json: JSON for AJAX.
csv: Comma-separated values for spreadsheets.
tsv: Tab-separated values for spreadsheets.
txt: Fixed width plain text for UNIVAC, ENIAC, VAX, teletype, or Mars rover.

callback

[string] Name of your function to call for JSON reqests. Ignored if output is not json.

HTML Output

HTML output generates a full HTML page in the Georgia Log Cabin template. This is what our own site uses. You might use this if you simply want to deep link users to the Georgia Log Cabin site for search results.

HTM Output

HTM output generates a full HTML page, but with no styling and no headers or footers. The page has all the normal html, head, title, and body tags, but no CSS or site navigation. you might use this if you want to present search results in a frame or iFrame on your site.

Questions:

• HTM results include opening and closing html, head, title, and body page tags. Would a bare HTML list without any of the document level tags be better?
• Please send any suggestions you have to search@GeorgiaLogCabin.org.

RSS Output

RSS output generates RSS 2.0 format results with the typical RSS fields, and a few Amazon A9 OpenSearch fields.

Example output:

Questions:

• RSS results are currently returned with MIME type application/xml. What MIME type is best?
• Please send any suggestions you have to search@GeorgiaLogCabin.org.

XML Output

XML output generates a custom XML format that generally follows the RSS field names, but has extra information like search relevance. Here is our XML search output DTD.

Example Output:

Questions:

• XML results are currently returned with MIME type application/xml. What MIME type is best?
• Please send any suggestions you have to search@GeorgiaLogCabin.org.

JSON Output

JSON output generates a custom JavaScript object that generally follows the RSS field names, but has extra information like search relevance.

Example Output (with callback=ShowResults used):

Questions:

• JSON results are currently returned with MIME type application/json. What MIME type is best?
• Please send any suggestions you have to search@GeorgiaLogCabin.org.

CSV Output

CSV output generates a plain text file of comma separated values that includes a header row, and search results on separate lines.

Example Output:

"Title","Description","Date","URL","Size","Relevance"
"Senators Frist, Allard and Santorum Should Allow Up or Down Vote on Federal marriage amendment","Log Cabin Republicans call on Senate Majority Leader Bill Frist (R-TN), Senator Rick Santorum (R-PA) and Senator Wayne Allard (R-CO) to allow an up or down vote on the anti-family Federal marriage amendment (FMA).","2004-07-13","http://www.GeorgiaLogCabin.org/news/200407131814.shtml","2977","44%"
"Log Cabin Denounces Federal marriage amendment","Log Cabin Republicans denounce the introduction of the Federal marriage amendment in the United States Senate.","2003-11-26","http://www.GeorgiaLogCabin.org/news/200311261440.shtml","2364","44%"
"Log Cabin to Senate Majority Leader: Vote on Anti-Family amendment Motivated by Politics","The Senate should be addressing real issues instead of playing politics with the Constitution.","2004-07-07","http://www.GeorgiaLogCabin.org/news/200407071233.shtml","6606","41%"
"Log Cabin Republicans Executive Director Patrick Guerriero on Granting of marriage Licenses in Massachusetts","Today hundreds of loving, law-abiding couples in Massachusetts will accept the responsibilities of caring for each other for life.","2004-05-17","http://www.GeorgiaLogCabin.org/news/200405171204.shtml","2284","41%"
"Log Cabin Responds to President Bush's Comments on the Future of the Anti-family Federal marriage amendment","Log Cabin responds to Bush statement on FMA.","2005-01-18","http://www.GeorgiaLogCabin.org/news/200501181132.shtml","1610","39%"

Questions:

• CSV results are currently returned with MIME type application/vnd.ms-excel. What MIME type is best?
• CSV results are currently returned with a content-disposition header for a file name of lcrgasearchresults.csv. Should content-disposition be used or not? Is a static file name OK, or should there be a dynamic file name?
• Please send any suggestions you have to search@GeorgiaLogCabin.org.

TSV Output

CSV output generates a plain text file of tab separated values that includes a header row, and search results on separate lines.

Example Output:

Title	Description	Date	URL	Size	Relevance
Senators Frist, Allard and Santorum Should Allow Up or Down Vote on Federal marriage amendment	Log Cabin Republicans call on Senate Majority Leader Bill Frist (R-TN), Senator Rick Santorum (R-PA) and Senator Wayne Allard (R-CO) to allow an up or down vote on the anti-family Federal marriage amendment (FMA).	2004-07-13	http://www.GeorgiaLogCabin.org/news/200407131814.shtml	2977	44%
Log Cabin Denounces Federal marriage amendment	Log Cabin Republicans denounce the introduction of the Federal marriage amendment in the United States Senate.	2003-11-26	http://www.GeorgiaLogCabin.org/news/200311261440.shtml	2364	44%
Log Cabin Responds to President Bush's Comments on the Future of the Anti-family Federal marriage amendment	Log Cabin responds to Bush statement on FMA.	2005-01-18	http://www.GeorgiaLogCabin.org/news/200501181132.shtml	1610	39%

Questions:

• TSV results are currently returned with MIME type application/vnd.ms-excel. What MIME type is best?
• TSV results are returned with a content-disposition header for a file name of lcrgasearchresults.xls. Should content-disposition be used or not? Is a static file name OK, or should there be a dynamic file name?
• Please send any suggestions you have to search@GeorgiaLogCabin.org.

TXT Output

TXT output generates a plain text file of fixed width values that includes a header row, and search results on separate lines. This is probably not useful to anyone, but was really easy to implement so what the heck.

Columns 1-50

Page title, truncated to 50 characters.

Columns 52-101

Page description, truncated to 50 characters.

Columns 103-112

Page publish or last update date in yyyy-mm-dd format.

Columns 114+

Page URL.

Title Description Date URL
Senators Frist, Allard and Santorum Should Allow U Log Cabin Republicans call on Senate Majority Lead 2004-07-13 http://www.GeorgiaLogCabin.org/news/200407131814.shtml
Log Cabin Denounces Federal marriage amendment Log Cabin Republicans denounce the introduction of 2003-11-26 http://www.GeorgiaLogCabin.org/news/200311261440.shtml
Log Cabin Responds to President Bush's Comments on Log Cabin responds to Bush statement on FMA. 2005-01-18 http://www.GeorgiaLogCabin.org/news/200501181132.shtml

Questions:

• TXT results are returned with a content-disposition header for a file name of lcrgasearchresults.txt. Should content-disposition be used or not? Is a static file name OK, or should there be a dynamic file name?
• Please send any suggestions you have to search@GeorgiaLogCabin.org.

Errors

Here are some proposed output errors. (None of these are implemented yet.)

10: Search term is empty

Currently a location redirect to our advanced search page is returned regardless of your requseted output format. Should this be an error, or just normal response with no results?

11: Search term was all stop words

Currently empty search results in your requested output format are returned. Should this be an error, or just normal response with no results?

20: Search term is an URL

Currently a location header redirect to the URL is returned regardless of your requested output format. Should this be an error, or just normal response with no results?

30: Could not open search index file

Currently this is presented as an HTML page regardless of your requested output format. How should this be returned?

Questions:

• How would you prefer to see errors implemented in XML, JSON, and the other formats?
• Please send any suggestions you have to search@GeorgiaLogCabin.org.

Output Property Definitions

Hopefully most of the output properties are obvious, but here's a description on each just in case. Not all properties are available in all output formats.

atom:link

This string identifies an equivalent URL for the query you just requested. It only appears in RSS output. See also link.

callback

This string is your callback function name you submitted with a JSON request, or an empty string if you did not specify a callback value in your request. This is only present when output is set to json.

description

This string is the long form description of the page identified in the search result. In the header of the RSS, XML, and JSON outputs, description is a sentence that identifies the search just performed. This is suitable for displaying to a user.

from

This string is the from date you submitted with your request, or the default value used if you did not specify it in your request.

guid

This string is a fully qualified URL for the location of a search result. The RSS and XML outputs also include an attribute isPermaLink which is always set to true.

height

This integer is the pixel height of a small image you can display along with the search results from our site.

ignoredTerms

This string identifies any query word in your request that was not applied to the search (i.e. a stop word.)

image

This object contains information about a small image you can display along with the search results from our site.

item

This object contains information about each search result from our site.

language

The string is language of the Georgia Log Cabin site. This is always en-us.

lastBuildDate

This string is the date and time the query was run. The format in RSS is dd Mon yyyy hh:mm:ss -0500.

link

This string is a fully qualified URL for the location of a page identified in the search result. In the header of the RSS, XML, and JSON outputs, link identifies an equivalent URL for the query you just requested.

mode

This string is the mode value you submitted with your request, or the default value used if you did not specify it in your request.

openSearch:itemsPerPage

This integer is the rows value you specified. It only appears in RSS output. See also rows.

openSearch:startIndex

This integer is the start value you specified. It only appears in RSS output. See also start.

openSearch:totalResults

This integer is the total number of available results from the site, not just the number results returned at any one time. It only appears in RSS output. See also total.

output

This string is the output value you submitted with your request, or the default value used if you did not specify it in your request.

pubDate

This string is the date a page identified in the search result was either originally published or last updated. News stories and press releases always include the original date the story was published. General information pages (like our About Us page) always include the date the page was last updated.

query

This string is the full search term you submitted.

relevance

This number is a normalized value of the relevance of each search result to the query term you submitted. In XML and JSON outputs, this number is a floating point value between 0 and 1. In CSV, TSV, and TXT outputs, this number is an integer percentage suitable for displaying to users. The most relevant result is either 1.00000 or 100%.

require

This string is the require value you submitted with your request, or the default value used if you did not specify it in your request.

results

This object is the root level element of the XML output. It contains all the header information and search results.

rows

This integer is the rows value you submitted with your request, or the default value used if you did not specify it in your request.

size

This integer is an approximate size in bytes of the search result page on the site. The actual page size is always larger because this value does not include additional SSI content added to every page.

sort

This string is the sort value you submitted with your request, or the default value used if you did not specify it in your request.

start

This integer is the start value you submitted with your request, or the default value used if you did not specify it in your request.

title

This string is the title of a page identified in the search result. This is suitable for displaying to a user.

to

This string is the to date you submitted with your request, or the default value used if you did not specify it in your request.

total

This integer is the total number of available results from the site, not just the number results returned at any one time.

url

This string is the URL of a small image you can display along with the search results from our site.

usedTerms

This string identifies any query word in your query that was actually applied to the search (i.e. words that are not stop words.)

width

This integer is the pixel width of a small image you can display along with the search results from our site.

To Do

• Implement ATOM output
• Chronological sort order (oldest first) for browse-by-date experience.
• Get feedback on XML, RSS, JSON, CSV and TSV output formats.
• Get feedback on appropriate MIME types