User Tools

Site Tools


numishare:search

Search API

The Search API is located at the apis/search pipeline (e.g., http://numismatics.org/ocre/apis/search). There are two required URL parameters: q (for Lucene syntax-compliant queries), format (atom or rss for OpenSearch-compliant results; note: the response will default to atom if the parameter is not set to an accepted format) and two optional parameters: sort (Lucene syntax-compliant sort parameter: default is relevancy) and start (the Solr start index, default is 0, and with 100 results per page, the page 2 index is start=100).

Response Formats

Currently results are proved in Atom (default) and RSS, with OpenSearch compliant fields. The responses are fairly similar. The feed contains several links defined by the 'rel' attribute: self, alternative (the text/html browse page), next (if available), last, and search (the opensearch description). It is possible to create a script which will iterate through all pages of the feed. Indeed one has already been written in PHP and is available in the Numishare trunk in tools/get-ids.php.

See below for examples:

Atom

<feed xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns="http://www.w3.org/2005/Atom"
      xmlns:gx="http://www.google.com/kml/ext/2.2"
      xmlns:atom="http://www.w3.org/2005/Atom"
      xmlns:georss="http://www.georss.org/georss"
      xmlns:oac="http://www.openannotation.org/ns/"
      xmlns:gml="http://www.opengis.net/gml/"
      xmlns:owl="http://www.w3.org/2002/07/owl#"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:skos="http://www.w3.org/2004/02/skos/core#">
   <title>Online Coins of the Roman Empire</title>
   <id>http://numismatics.org/ocre/</id>
   <link rel="self" type="application/atom+xml"
         href="http://numismatics.org/ocre/apis/search?q=rev_type_text:snake&amp;start=0"/>
   <link rel="alternative" type="text/html"
         href="http://numismatics.org/ocre/results?q=rev_type_text:snake&amp;start=0"/>
   <link rel="last" type="application/atom+xml"
         href="http://numismatics.org/ocre/apis/search?q=rev_type_text:snake&amp;start=100"/>
   <link rel="search" type="application/opensearchdescription+xml"
         href="http://numismatics.org/ocre/opensearch.xml"/>
   <author>
      <name/>
   </author>
   <opensearch:totalResults>171</opensearch:totalResults>
   <opensearch:startIndex>0</opensearch:startIndex>
   <opensearch:itemsPerPage>100</opensearch:itemsPerPage>
   <opensearch:Query role="request" searchTerms="rev_type_text:snake" startPage="0"/>
   <entry>
      <title>RIC III Antoninus Pius 1038</title>
      <link href="http://numismatics.org/ocre/id/ric.3.ant.1038"/>
      <id>ric.3.ant.1038</id>
      <updated>2012-09-12T18:12:24.312Z</updated>
      <link rel="alternate xml" type="text/xml"
            href="http://numismatics.org/ocre/id/ric.3.ant.1038.xml"/>
      <link rel="alternate rdf" type="application/rdf+xml"
            href="http://numismatics.org/ocre/id/ric.3.ant.1038.rdf"/>
      <georss:where>
         <gml:Point>
            <gml:pos>41.9 12.5</gml:pos>
         </gml:Point>
      </georss:where>
      <gx:TimeSpan>
         <begin xmlns="">159</begin>
         <end xmlns="">160</end>
      </gx:TimeSpan>
   </entry>
 </feed>

RSS

<rss xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:dcterms="http://purl.org/dc/terms/"
     xmlns:gx="http://www.google.com/kml/ext/2.2"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:georss="http://www.georss.org/georss"
     xmlns:oac="http://www.openannotation.org/ns/"
     xmlns:gml="http://www.opengis.net/gml/"
     xmlns:owl="http://www.w3.org/2002/07/owl#"
     xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
     xmlns:skos="http://www.w3.org/2004/02/skos/core#"
     version="2.0">
   <channel>
      <title>Online Coins of the Roman Empire</title>
      <description>Numishare Collection</description>
      <link>http://numismatics.org/ocre/</link>
      <copyright>Copyright: American Numismatic Society</copyright>
      <atom:link rel="self" type="application/atom+xml"
                 href="http://numismatics.org/ocre/apis/search?q=rev_type_text:snake&amp;start=0"/>
      <atom:link rel="alternative" type="text/html"
                 href="http://numismatics.org/ocre/results?q=rev_type_text:snake&amp;start=0"/>
      <atom:link rel="last" type="application/atom+xml"
                 href="http://numismatics.org/ocre/apis/search?q=rev_type_text:snake&amp;start=100"/>
      <atom:link rel="search" type="application/opensearchdescription+xml"
                 href="http://numismatics.org/ocre/opensearch.xml"/>
      <opensearch:totalResults>171</opensearch:totalResults>
      <opensearch:startIndex>0</opensearch:startIndex>
      <opensearch:itemsPerPage>100</opensearch:itemsPerPage>
      <opensearch:Query role="request" searchTerms="rev_type_text:snake" startPage="0"/>
      <item>
         <title>RIC III Antoninus Pius 1038</title>
         <link>http://numismatics.org/ocre/id/ric.3.ant.1038</link>
         <pubDate>2012-09-12T18:12:24.312Z</pubDate>
         <georss:where>
            <gml:Point>
               <gml:pos>41.9 12.5</gml:pos>
            </gml:Point>
         </georss:where>
         <gx:TimeSpan>
            <begin>159</begin>
            <end>160</end>
         </gx:TimeSpan>
      </item>
    </channel>
  </rss>

Solr Fields

'*:*' = everything

Textual Fields

These fields typically are dynamic fields defined by the Solr schema and contain a _text suffix.

Types and Legends
  • legend_text = legend (obverse and reverse)
  • obv_leg_text = obverse legend
  • obv_type_text = obverse type
  • rev_leg_text = reverse legend
  • rev_type_text = reverse type
  • type_text = type (obverse and reverse)
People and Places
  • artist_text = artist
  • authority_text = authority
  • deity_text = deity
  • engraver_text = engraver
  • findspot_text = findspot
  • issuer_text = issuer
  • locality_text = locality (sub-set of region in Mantis only)
  • maker_text = maker
  • mint_text = mint
  • portrait_text = portrait (person appearing on coin)
  • region_text = region
  • state_text = nation-state (type of authority)
Other
  • fulltext = keyword search anywhere in the record

String Fields (Facets)

These strings are case sensitive and must be matched precisely unless with wildcards. Values which contain whitespace or special characters should be enclosed in double quotes. Note that most of these facets are typological and URIs (from nomisma, viaf, geonames, etc.) can be queried with *_uri (e.g., mint_uri:“http://nomisma.org/id/rome”), including the pleiades_uri field.

People and Places
  • artist_facet = artist
  • authority_facet = authority
  • deity_facet = deity
  • dynasty_facet = dynasty
  • engraver_facet = engraver
  • findspot_facet = findspot
  • issuer_facet = issuer
  • locality_facet = locality (sub-set of region in Mantis only)
  • maker_facet = maker
  • mint_facet = mint
  • portrait_facet = portrait (person appearing on coin)
  • region_facet = region
  • state_facet = nation-state (type of authority)
Typological
  • color_facet = color
  • degree_facet = degree (for decorations)
  • denomination_facet = denomination
  • era_facet = era
  • manufacture_facet = method of manufacture
  • material_facet = material
  • objectType_facet = object type
Other
  • department_facet = department
  • dob_num = date on object
  • grade_facet = grade
  • id = Solr record id, derived from the nudsHeader/nudsid
  • imagesavailable = set to 'true' to query if images are available for the record
  • institution_facet = institution
  • owner_facet = owner
  • recordType = record type: 'conceptual', 'physical', or 'hoard'
  • reference_facet = bibliographic reference
  • repository_facet = repository
  • series_facet = series
  • subject_facet = subject

Numeric Fields

Numeric fields can be either integer values (Solr field type sint, sortable integer) or floating point values (sfloat, sortable float). These fields are optimal for range searches.

Integers
  • axis_num
  • century_num
  • decade_num
  • taq_num = terminus ante quem (used for hoards)
  • tpq_num = terminus post quem (used for hoards)
  • year_num
Floating Point Numbers
  • diameter_num
  • height_num
  • thickness_num
  • weight_num
  • width_num

Sortable Fields

By default, Solr will sort results by relevancy. The sort URL parameter can be supplied to the Search API to sort the results. The syntax is as follows: '{sort field} {sort order}'. The sort order is 'asc' for ascending or 'desc' for descending, e.g., 'diameter_num asc' to order results from smallest to largest diameter.

Due to fairly recent changes to Solr, multivalued Solr fields cannot be selected for sorting. Instead, upon the indexing of the record into Solr, the lowest string value for a field (usually a facet) is giving a _min dynamic field suffix, and the highest string value is given a _max suffix. For multivalued numeric fields (e.g., year_num), the _minint and _maxint suffixes are given.

The following sortable fields are supported:

  • authority (_min and _max)
  • axis_num
  • dob (_min and _max)
  • timestamp
  • degree (_min and _max)
  • deity (_min and _max)
  • denomination (_min and _max)
  • department (_min and _max)
  • diameter_num
  • dynasty (_min and _max)
  • findspot (_min and _max)
  • issuer (_min and _max)
  • manufacture (_min and _max)
  • material (_min and _max)
  • mint (_min and _max)
  • obv_leg_display
  • portrait (_min and _max)
  • region (_min and _max)
  • rev_leg_display
  • weight_num
  • year (_minint and _maxint)

The axis_num, timestamp, diameter, weight, obv_leg_display, and rev_leg_display fields are not repeatable in the Solr schema, and therefore they do not need _min or _max suffixes. See below for example searches.

Example Searches

Quinarii in order from latest date first: http://numismatics.org/ocre/apis/search?q=denomination_facet:Quinarius&format=atom&sort=year_maxint%20desc

Roman imperial coins from A.D. 68 to 69 ordered by mint ascending (Africa to Vindobona): http://numismatics.org/ocre/apis/search?q=year_num:[68%20TO%2069]&format=atom&sort=mint_min%20asc

Roman imperial coins from A.D. 68 to 69 ordered by mint descending (Vindobona to Africa): http://numismatics.org/ocre/apis/search?q=year_num:[68%20TO%2069]&format=atom&sort=mint_max%20desc

Roman imperial coins from Vindobona with Pleiades URI search: http://numismatics.org/ocre/apis/search?q=pleiades_uri:"http://pleiades.stoa.org/places/128537"

Roman imperial coins with EX* AUG* anywhere in the legend: http://numismatics.org/ocre/apis/search?q=legend_text:EX*%20AUG*

Roman imperial coins with the keyword snake in the reverse type, sorted by denomination ascending (As to Sestertius): http://numismatics.org/ocre/apis/search?q=rev_type_text:snake&sort=denomination_min%20asc

numishare/search.txt · Last modified: 2012/11/19 21:10 by egruber