Metasearch/API

From GenWiki

Jump to: navigation, search

genealogy.net' meta-search http://meta.genealogy.net uses a simple API for an easy connection of additional search engines.

Contents

API

Via HTTP POST[1] with Content-Type application/x-www-form-urlencoded[2] these request parameters are send to the search engine:

  • lastname - the family name the user is looking for
  • placeid - GOV-Id of a place
  • placename - name of the place the user is looking for
  • since - (optional) only return entries that are youger than the specified date. If the search engine does not process this parameter the genealogy.net-Alerts won't work. Date format is yyyy-mm-dd

The values of the request will be linked with AND. It should go without saying that also non-ASCII characters (eg umlauts) can be searched. By default, requests will be UTF-8 encoded. However, it is possible to switch to ISO-8859-1 if the implementation of UTF-8 is too difficult for a search engine operator.

The expected response (HTTP Content-Type must be 'text/xml'!) looks like this:

<result>
  <database>
    <name>GEDBAS</name>
    <url>http://gedbas.genealogy.net</url>
    <entry>
      <lastname>lastname 0</lastname>
      <firstname>firstname 0</firstname>
      <details>details 0</details>
      <url>http://localhost/data/0</url>
    </entry>
    <entry>
      <lastname>lastname 1</lastname>
      <firstname>firstname 1</firstname>
      <details>details 1</details>
      <url>http://localhost/data/1</url>
    </entry>
    ...
    <more>true</more>  <!-- The presence of the "more" element indicates that the database contains more results than the already transmitted ones. -->
  </database>
</result>

If the search request is empty (neither lastname, nor placeid, nor placename are given) an empty result (and no error message) must be returned:

<result>
  <database>
    <name>GEDBAS</name>
    <url>http://gedbas.genealogy.net</url>
  </database>
</result>

The same result must be returned if not hits could be found:

<result>
  <database>
    <name>GEDBAS</name>
    <url>http://gedbas.genealogy.net</url>
  </database>
</result>

Further information

Do I have to return 20 hits?

No. You might also return only 5 hits via the meta search and show the other results only via your own webpage. However, too many entries make the result confusing for the user. Therefore 20 entries per database seems to be a good value to us.

What happens if I run mutiple databases?

Since a <result> element allows more than one <database> element one requenst might return results for multiple databases. This is a decision of the search engine operator. Note, however, that a user might be confused to see results various databases afte selecting only a single database on the start page of the meta search.

Example implementations

PHP

<?php
# A helper function reading the content of the HTTP parameters.
function get_http_var($name, $default=''){
  global $_GET, $_POST;
  if (array_key_exists($name, $_GET)){return trim($_GET[$name]);}
  if (array_key_exists($name, $_POST)){return trim($_POST[$name]);}
  return $default;
}
 
$lastname  = get_http_var('lastname');
$placename = get_http_var('placename');
$govId = get_http_var('placeid');
 
header('Content-type: text/xml');
echo "<result>";
echo "<database>";
echo "<name>Example DB</name>";
echo "<url>http://example.org</url>";
 
# Perform the query and iterate over the results
for( $i = 0; $i < $number_of_results; $i++ ) {
 
  echo "<entry>";
  echo "<lastname>...</lastname>";
  echo "<firstname>...</firstname>";  # If the database does not contain given names, this element can be omitted
  echo "<details>...</details>";      # The details can contain any information, eg birth and death date and place
  echo "<url>http://example.org/item?id=...</url>"; # a direct link to the entry
  echo "</entry>";
 
} # for the results

# If there are more results than beeing returned an element "more" is inserted.
if( $number_of_results > 20 ) {
   echo "<more>true</more>";
}
 
echo "</database>";
echo "</result>";
?>

Grails

if( !(params.lastname || params.placename || params.placeid) )
  render(contentType:"text/xml") {
    error()
  }
 
def criteria = Entry.createCriteria() 
def results = criteria.list([max:21]) {
  // do the search
}
 
render(contentType:"text/xml") {
  'result' {
    database {
        name('Datenbank Historischer Adressbücher')
        url('http://adressbuecher.genealogy.net')
        for( int i = 0; i< Math.min(results.size(),20); i++) {
            Entry e = results[i]
            entry {
                lastname(e.lastname)
                firstname(e.firstname)
                details("${e.book?.title} ${e.book?.year}")
                url(g.createLink(controller:'entry',action:'show',id:e.id,absolute:true))
            }
        }
        if( results.size()> 20 )
            more('true')
    }
}

  1. Unfortunalety, the HTTP standard contains contradicting information how to handle non-ASCII characters in a GET request. This caused a lot of trouble in earlier versions of the API. Using POST requests it is possible to specified the character set. Therefore, the problems do not occur with POST request.
  2. http://en.wikipedia.org/wiki/POST_(HTTP)#Use_for_submitting_web_forms
Personal tools
GenWiki-internal
In other languages