Linking to the data

We hope to make IPNI available as a web service eventually. Meanwhile by publishing the urls which our servlets use for searching the data we can at least allow other users to put in links to our search result pages.

IPNI is now also an LSID server - see the LSID server page for more information.

It is now also possible to retrieve individual plant name records in RDF format - see under Retrieving a Full Name Record by Id for details of how. The RDF format has been based on the TDWG standard Taxon Concept Transfer Schema.

• Before you start

• How the URLs work

• A note on Wild cards

• A note on the Mirrors

• Searching for Names

• Retrieving a Full Name Record by Id

• Name 'quick searches'

• Searching for Publications

• Retrieving a Full Publication Record by Id

• Searching for an Author

• Retrieving a full Author Record by Id

• Output Formats

Before you start

Please note that these URLs have changed as of August 2006. While the old ones will still work, we suggest you update any links you may have made. We also suggest that you email us if you are planning to use these URLs so that we can warn you if we're about to change them.

The IDs linked, however are immutable - that is to say we guarantee that the ids exposed in the searches and links will always refer to those names. As we start to deduplicate we will be making links between duplicated names and deprecating the less up to date, complete, or accurate one. Therefore you may find that a search which currently returns 70 hits may, over the course of time return fewer as some of the redundant records are suppressed. They haven't gone away, however, they are just hiding, and any link to one of these suppressed records by ID will not fail. Users will now usually be redirected to another record (where appropriate) or warned that a record has been suppressed.

If you want to know more about the searches themselves and how to retrieve the information you want from them, reading the understanding the data pages will help. Note that all searches on IPNI are case insensitive, but that the parameter names are case sensitive 'find_surname=crOFt' will work fine, but 'Find_Surname=Croft' will not.

How the URLs work

Here's a typical URL:

http://www.ipni.org/ipni/advPlantNameSearch.do?find_family=&find_genus=Brintonia&find_species=& find_infrafamily=&find_infragenus=&find_infraspecies=&find_authorAbbrev=& find_includePublicationAuthors=on&find_includePublicationAuthors=off& find_includeBasionymAuthors=on&find_includeBasionymAuthors=off& find_publicationTitle=&find_isAPNIRecord=on&find_isAPNIRecord=false& find_isGCIRecord=on&find_isGCIRecord=false&find_isIKRecord=on& find_isIKRecord=false&find_rankToReturn=all&output_format=normal& find_sortByFamily=on&find_sortByFamily=off

Choosing 'copy Shortcut' and pasting this into the location window in your browser, or simply clicking on this URL, will cause a search on the Genus 'Brintonia' including records from all three of the indexes. The format of the URL is as follows:

The address of the server: http://www.ipni.org
The location and name of the particular search: ipni/advPlantNameSearch.do
The parameters, in the form: parameter name=parameter value
note that the parameter list is preceded by a question mark: ? and each parameter is joined by an ampersand: &

You can also see that some of these parameters are blank, and these ones are actually not required. You can get the same result using the following, much shorter, URL:

http://www.ipni.org/ipni/advPlantNameSearch.do?find_genus=Brintonia&find_isAPNIRecord=on& find_isGCIRecord=on&find_isIKRecord=on&output_format=normal

The tables below will tell you what parameters and values you need for each type of search.

A note on Wild cards

IPNI uses the standard SQL wildcard for retrieving inexact matches from the database: '%' means '0, 1 or more characters', so searching on 'Poa%' for a genus will retrieve records for both Poa and Poagrostis. Don't use the single character wildcard ('_') as this can cause problems with the server.

If you want to use wild cards in your links to IPNI, the '%' character must be followed by '25', so the parameter for the search on 'Poa%' described above would need to be 'genus=Poa%25'in order to work.

Back to top

A note on the Mirrors

IPNI uses mirrored servers in order to ensure consistency of service. In general, you should not specify which mirror server you want, but always use 'www.ipni.org' as the first part of your URL. However, if you do want to specify a particular server then you can do so by inserting the country code before the 'ipni' as in: 'www.us.ipni.org' or 'www.uk.ipni.org'. For a list of available mirrors, check the mirrors page.

Searching for Names

These searches retrieve lists of names by matching on name, author abbreviation or place of publication. Wild cards may be used, but not at the beginning of a search term.

Search Name: advPlantNameSearch.do

Parameters:

Please note that even though some of the parameters are optional, at least one of find_family, find_infrafamily, find_genus, find_infragenus, find_species, find_infraspecies, find_publicationTitle, find_authorAbbrev or the extended search parameter find_geoUnit must be supplied. find_addedSince and find_modifiedSince may only be used in conjunction with other query parameters.

Back to top

Retrieving a Full Name Record by ID

The URL for retrieving a full name record by its ID is much simpler. There is only one required parameter and two optional ones. No wild cards are allowed and only one record will be retrieved.

Here's a typical URL for retrieving a single record by id:

http://www.ipni.org/ipni/idPlantNameSearch.do?id=416415-1

Search Name: idPlantNameSearch.do

Parameters:

Back to top

Searching for a publication

Publications can be searched for either by their full name or their abbreviation. Note that the names are often extremely long so you are likely only to get a match by including wild cards in your search terms. Note also that the Publication search is different from the plant name search and so has a different URL

Here's a typical url for retrieving a list of publications:

http://www.ipni.org/ipni/advPublicationSearch.do?find_title=Rhod%25&find_abbreviation= &output_format=normal

Search Name: advPublicationSearch.do

Parameters:

Note that although some of the parameters are optional at least one of find_title or find_abbreviation must be supplied for the link to work.

Back to top

Retrieving a publication by ID

This retrieves the full publication record. Only one publication record will be retrieved and wild cards are not allowed. The format of the URL is very similar to that for retrieving a plant name or author by id.

Search Name: idPublicationSearch.do

Parameters:

Back to top

Searching for an Author

Authors can be searched for by name (surname and or forenames or initials), by abbreviation or by the country they worked in or were associated with.

A typical URL might look like this:

http://www.ipni.org/ipni/advAuthorSearch.do?find_forename=&find_surname=Croft&find_abbreviation= &find_isoCountry=&output_format=normal

Wild cards are allowed and may be necessary in order to handle names with diacritics in them (See the search tips for more information on this.

Search Name: advAuthorSearch.do

Parameters:

Note that although some of the parameters are optional at least one of find_forename, find_surname, find_isoCountry or find_abbreviation must be supplied for the link to work

Back to top

Retrieving an Author by ID

This retrieves the full author record by id, and is very similar to those needed for publication or plant name records.

Search Name: idAuthorSearch.do

Parameters:

Output Formats

By default, IPNI outputs to HTML for easy viewing on the screen, but we have now added a variety of delimited data output formats as well as the full record listing.

Selecting any one of the 'delimited' returns a '%' delimited file, which has column headers as the first row and can be imported into a spreadsheet, database or word processing application for further manipulation. Delimited results are displayed without paging but the number of records retrieved is limited to 5,000 records in total (compared to 50,000 records for the normal format). If you would like a larger amount of data in delimited format please contact us. Because more data per record is accessed initially in delimited format, and more than 100 records are displayed at a time, using the delimited option is likely to be slower than using the normal results format.

For more information on the fields returned in the delimited formats, see our delimited help pages

Selecting 'full records' returns a paged result list as for 'normal', but instead of each record being on a single line with links through to the full record, all of the information for the records on each page are displayed on the results page. This is useful if you are scanning through looking for a particular detail that doesn't get shown on the result line (for example a country for an author or a type specimen for a taxon name) but you should be aware that your results will be retrieved and displayed more slowly than if you had selected the usual output format, especially if more than a dozen or so records have been retrieved.

We also plan to offer more IPNI data in XML or RDF format. The format for Plant names is likely to be the recently adopted TDWG standard Taxon Concept Transfer Schema (TCS). For now only individual records can be retrieved in this format.

Back to IPNI Home