Home » Implementation Guides and HowTos

Getting Started Creating OpenURLs

This is a guide to getting started creating URL Key-Value (KEV) format OpenURLs of format 'journal'. Existing documentation can be overwhelming for the newcomer, so this is meant to be an easy start. The intended audience is people writing software that will generate OpenURLs pointing to an OpenURL link resolver.

Note that we gloss over some complexities here. More complete introduction to generating KEV OpenURLs can be found at the Z39.88-2004 KEV Implementation Guidelines. Note also that 'journal' is just one available format for scholarly citations; that all scholarly citations can be sent in an XML format rather than KEV (confusingly this is still called 'OpenURL'); and that scholarly citations are just one available use of OpenURL. That's why this gets so overwhelming, and why I wrote this guide for a gentle introduction to the most common use case.

Your OpenURL will begin with a 'base' for a particular OpenURL link resolver. For instance, Johns Hopkins Umlaut 'base' is:

http://findit.library.jhu.edu/resolve?

After that comes a number of URL parameters revealing the format you are sending, the metadata for the citation being sent, and optionally other information about the context. Following is a description of the most common elements you need for a basic journal citation OpenURL. Note that all values are URL-encoded.

# Include some "fixed" fields that should always be there just like this, that just identify that what you are sending is an OpenURL, the version, the char encoding (UTF-8), etc.


&url_ctx_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Actx
&ctx_ver=Z39.88-2004
&url_ver=Z39.88-2004
&ctx_enc=info%3Aofi%2Fenc%3AUTF-8

# The rfr_id parameter identifies the software generating
# the OpenURL. The value is an "sid" format ("source id").
# It is based on an identifier that looks like a hostname
# in a domain you control, followed optionally by a sub-part.
# For instance, for a meta-search tool at Welch Medical Library,
# the sid might look like:
# info:sid/article-search.welch.jhu.edu
#
# Optionally you can add a sub-part. If a metasearch of
# pubmed were used to retrieve the citation being sent:
# info:sid/article-search.welch.jhu.edu:pubmed
#
# The whole value needs to be URL encoded:


&rfr_id=info%3Asid%2Farticle-search.welch.jhu.edu%3Apubmed

# Now the parameters that actually identify the citation.
# First you have to tell it what kind of citation it is. This
# next line says it's a journal article citation. You can also
# send 'book', and other kinds of citations, which give you
# different available metadata elements. But our
# quick-start guide just assumes journal.


&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal

# Now actually identify the article. If possible, as a minimum,
# you should send ISSN, year, volume, issue, and start page.


rft.issn=0936-6555
# This should be in format yyyymmdd, or just yyyymm,
# or just yyyy.
&rft.date=2008
&rft.volume=2008
# start page
&rft.spage=53
&rft.issue=1

# If you have a pubmedID (pmid) or a DOI, you can include them with rft_id. First create
# a pmid or DOI identifier like this:
# info:pmid/18345545
# or info:doi/389473894738
#
# Then URL encode it, for example:


&rft_id=info%3Apmid%2F18345545

# If you have author, title, and end page information, they can also be sent along, although it's not neccesarily required:


&rft.aufirst=
&rft.aulast=
# If you can't seperate out first and last you can use:
&rft.au=
# end page
&rft.epage=
# Title of containing journal
rft.jtitle=
# Title of particular article
rft.atitle

MORE RESOURCES