In addition to a website that allows users to search and display inscriptions from the IIP collection, we also provide a web API so that technical users can access our corpus as data that they can process themselves.
An API (Application Programming Interface) is a piece of software that makes it possible for two programs to communicate. IIP provides a web API, which means that it is possible to issue a series of special URLs that will return IIP information as data – in XML or in Json format – instead of an attractive and human-readable web display. These formats make our corpus data reusable by other projects and programs. For example, in the case of IIP you might use our API instead of manually searching for inscriptions if you wanted to gather statistics or display the inscriptions geographically on a map (like we do!). In certain cases, you may also have access to more information through an API than you would otherwise. For example, in building a map you would use our API to gather geographic coordinates, information that each inscription has but that isn’t generally displayed when you look at an inscription on our website. APIs are amazingly useful — for more information and a general introduction, see the documentation provided by the Digital Public Library of America.
Our API
The IIP API connects you to our collection of inscription data by sending queries to the Solr index powering our search interface. Simply put, the API asks Solr for information and Solr returns it in a nicely structured format that is easy to re-use. If you want more detail, or if you’re interested in using Solr for your own project, you should check out the Solr documentation.
The queries that you send through our API will rely on IIP keywords and metadata and will return IIP metadata and IIP IDs (each inscription in the database has a unique ID). The way you piece together the query you want has a standard format defined by Solr. If you need more detail than what we provide here (see below), check out their documentation.
Accessing Specific Inscription Files
The inscription files themselves are XML files encoded using Epidoc and can be accessed in their XML form by appending the IIP ID to the URL https://search.inscriptionsisraelpalestine.org/inscriptions/ .
The IIP ID takes the form aaaa1111 or aaaa1111a (where a stands for an alphabetic character and 1 stands for a number). Please note that although the URL path may change, the IIP ID will not.
For example, the following URL will link to the XML file of inscription akld0007: https://search.inscriptionsisraelpalestine.org/inscriptions/akld0007
(This is an image of the inscription encoded in AKLD0007!)
The page above will look the same as the page you get when you select “view as XML” after selecting a specific inscription on our website. Try it – do a Text Search for AKLD0007, and select [View in XML] from the links below the image of the inscription.
Using the API to Search
In order to request information using our API, you’ll need to construct the exact URL for the search parameters you want. The URL will always start the same way: http://library.brown.edu/search/solr_pub/iip/?
From there, you’ll append a series of Solr parameters separated by the ampersand &. Parameter values are added following an equals sign =. Most of these parameters are generally available to all Solr queries and not specific to IIP content. For example, API queries can return xml or json formats, depending on the value of the wt flag: wt=xml or wt=json. You can specify how many results you want returned using start=0&rows=100 – in this case, you are requesting the first 100 hits . The q parameter lets you construct content-specific IIP queries (see example #2 and the chart below). A nicely compact summary of constructing Solr queries can be found here.
Some example queries:
- Find the first 100 inscriptions:
http://library.brown.edu/search/solr_pub/iip/?start=0&rows=100&indent=on&wt=json&q=*
The resulting web page is in the Json data format (wt=json). If you look at the results carefully, you will see Name-Value pairs that provide information derived primarily from the inscription metadata that is stored in the Epidoc Header. - Find the first 100 inscriptions that are from the region “Coastal Plain”:
https://library.brown.edu/search/solr_pub/iip/?start=0&rows=100&indent=on&wt=json&q=region:%22Coastal+Plain%22
In this example,regionis one of IIP’s facets, which means you can define a value for it using a colon and then useregion:"Coastal Plain"as your value for the Solr parameterq. However, note that double quotes “” in the URL must be encoded as %22. - You might be wondering how you would know that “Coastal Plain” is a possible value for the field
regionin the previous example — or how you know thatregionis a facet. Sometimes it is helpful to get information that is aggregated across the whole corpus, in order to then be able to formulate other queries that are based on specific details. This query will give you a list of all theregionattributes that are used in the IIP corpus:
http://library.brown.edu/search/solr_pub/iip/?start=0&rows=0&indent=on&facet=on&facet.field=region&wt=json - And this query will give you a CSV list of our facets, some of which are also in the table below:
https://library.brown.edu/search/solr_pub/iip/?q=:&start=0&rows=0&indent=on&wt=csv&facet