-
Notifications
You must be signed in to change notification settings - Fork 4
LibraryRegistryPublicAPI
The library registry presents a public API for clients that are trying to match library patrons with libraries that serve them.
Apart from the registration endpoint (which is covered elsewhere), all documents served by the library registry will either be problem detail documents or OPDS 2.0 catalogs.
OPDS 2.0 catalogs will be served with the profile http://librarysimplified.org/rel/profile/directory, which refers to the extensions defined in this document to talk about directories of OPDS servers. That is, OPDS 2.0 catalogs served by the library registry will have a media type of application/opds+json;profile=http://librarysimplified.org/rel/profile/directory.
The OPDS 2.0 JSON schema is here. Because we use a custom role, a library registry feed won't validate against this schema; we can probably figure out a workaround if this is a problem. The Readium Web Publication Manifest JSON schema is here, and I'd expect a library registry feed to validate against that.
Note that templated links are defined as per RFC 6570 -- the same standard used by OPDS 2.0.
The Feedbooks catalog is a solid sample implementation of OPDS 2.0. If you notice any unexplained discrepancies between the Feedbooks catalog and the OPDS served by the library registry, please let Leonard or Nick know -- the registry OPDS is more likely than the Feedbooks OPDS to be wrong.
To express the special capabilities of the library registry we had to adopt a number of terms from the schema.org vocabulary (something supported natively by OPDS 2.0) as well as define a number of extensions.
OPDS catalogs are designed to talk about publications, but the library registry doesn't have any books of its own. Instead, it talks about other OPDS catalogs.
The catalogs collection role contains a list of information about other OPDS catalogs. Each entry in the collection may have a metadata object and a links collection.
The OPDS 2.0 spec says a catalog feed "must contain at least one collection identified by the following roles: navigation, publications or groups." This implies that an OPDS catalog must provide direct access to books. The library registry knows about catalogs, not books, so it uses the catalogs role instead. This is what stops our feeds from validating against the OPDS 2.0 schema.
The schema:areaServed property may be present in an OPDS entry's metadata. It represents the geographic area serviced by a library, in a concise human-readable form. (As opposed to the much more detailed GeoJSON format available through following a link with rel="http://librarysimplified.org/rel/registry/focus".)
It is used as defined by schema.org. It is a property of type Text.
- Postal codes, states, provinces, and nations are presented as-is: e.g. “93203”, “Texas”, “United States”.
- For cities, the abbreviation for the state or province is affixed, e.g. “Truth or Consequences, NM”
- For counties, the string “County” and the state/province abbreviation is affixed, e.g. “Kings County, NY”.
- No
schema:areaServedis given for libraries whose service area is "everywhere", missing, or too complex to have a concise human-readable explanation.
The distance property may be present in an OPDS entry's metadata. It represents the distance, if known, between a library's areaServed and the client's geographic location (i.e. the geographic point provided in the query parameter location). It is used as defined by schema.org. It is a property of type Distance and its value is always given in kilometers, e.g. 301 km.
The distance property will not be present in any results if the server doesn't have a user-provided point to measure distance to. It may also be omitted for a library where "distance to the library's areaServed" doesn't make sense as a concept -- e.g. the Internet Archive.
We've defined a controlled vocabulary for talking about different types of libraries. We'll use the standard 'subject' feature of OPDS 2 to explain what type of library you're looking at. The URI of this scheme is http://librarysimplified.org/terms/library-types.
Here are the valid codes (to be updated as necessary):
-
local- A library that serves a small geographic area such as a city or town. -
county- A library that serves an entire county (in a country like the US or UK that has counties). -
state- A library that serves a state (in a country like the US or Australia that has states). -
province- A library that serves a province (in a country like Canada that has provinces). -
national- A library that serves an entire nation. -
universal- A library that serves everyone, without geographic restriction.
"subject" : [ { "name": "State library", "code": "state", "scheme": "http://librarysimplified.org/terms/library-types" } ]
- Since the
catalogscollection is full of catalogs, not books, we use theimagessubcollection to give you library logos, rather than cover images. To start with, we will deliver library logos as embeddeddata:URLs.
-
http://librarysimplified.org/rel/registry/focus- Links to anapplication/geo+jsonfile that shows a library's service area. -
http://librarysimplified.org/rel/registry/eligibility- Links to anapplication/geo+jsonfile that shows the area in which people are eligible for library service. For most libraries this is the same as the service area, but it may be larger. -
help- An email address or web page provided by this library to handle patron help requests.
You probably won't need these yet; the GeoJSON documents aren't used in SimplyE at present and the other links can be obtained from a library's authentication document.
The root endpoint is an OPDS 2 feed containing an empty list of catalogs. More importantly, it contains a links collection which includes one templated link for each of the other endpoints.
{
"metadata" : {
"title" : "SimplyE Library Registry"
},
"links" : [
{
"title": "SimplyE Library Registry",
"rel": "self",
"href": "https://libraryregistry.librarysimplified.org/",
"type" : "application/opds+json;profile=http://librarysimplified.org/rel/profile/directory"
},
{
"title" : "Libraries near me",
"rel" : "http://librarysimplified.org/terms/rel/nearby",
"href" : "https://libraryregistry.librarysimplified.org/nearby{?location,stage}",
"type" : "application/opds+json;profile=http://librarysimplified.org/rel/profile/directory"
},
{
"rel": "search",
"title": "Find my library",
"href" : "https://libraryregistry.librarysimplified.org/search{?query,location,stage}",
"type" : "application/opds+json;profile=http://librarysimplified.org/rel/profile/directory"
},
{
"rel": "register",
"title": "Register a library",
"href": "https://libraryregistry.librarysimplified.org/register",
"type": "application/opds+json;profile=http://librarysimplified.org/rel/profile/directory",
},
],
"catalogs": []
}
This endpoint is unusual in that it's used not by clients trying to match people to libraries, but by library circulation servers that want to participate in that matchmaking process. The link relation is register and the protocol is described here.
The proximity endpoint is used to find libraries near a provided geographic point.
http://librarysimplified.org/terms/rel/nearby
/nearby{?location,stage}
-
location- Required. A comma-separated pair of numbers to be interpreted as a point of latitude and longitude. As an example,40.7769,-73.9813refers to a point on New York's Upper West Side. Latitude and longitude may be specified to any precision, but the library registry will interpret40,-73as a point (off the coast of New Jersey) rather than an area. -
stage- Optional. This should either beproductionorall. Ifproduction, only libraries currently in the production stage will be considered for inclusion. Ifall, all libraries will be considered for inclusion. The default isproduction.
/nearby?location=40.7769,-73.9813/nearby?location=29.7,-95.3&stage=all
The representation is an OPDS 2 feed that uses the custom catalogs role to link to other OPDS servers. You should expect a feed that contains 3-5 entries.
Here's a sample representation with a single OPDS server in the collection with the catalogs role.
{
"metadata" : {
"title" : "Libraries near 40.7769,-73.9813"
},
"links" : [
{
"title": "Libraries near 40.7769,-73.9813",
"rel": "self",
"href": "https://libraryregistry.librarysimplified.org/nearby?location=40.7769,-73.9813",
"type" : "application/opds+json;profile=http://librarysimplified.org/rel/profile/directory"
}
],
"catalogs": [
{
"metadata": {
"title": "Brooklyn Public Library"
"identifier": "urn:uuid:edef2358-9f6a-4ce6-b64f-9b351ec68ac4",
"modified": "2021-01-12T17:48:06Z",
"schema:distance": "14 km.",
"schema:areaServed": "Kings County, NY"
"subject" : [
{
"name" : "Local library",
"scheme" : "http://librarysimplified.org/terms/library-types",
"code" : "local"
}
]
},
"images": [
{
"href": "data:image/png,...",
"type": "image/png",
"height": 200,
"width": 200
},
],
"links": [
{
"href": "https://bplsimplye.bklynlibrary.org/NYBKLYN/",
"type": "application/atom+xml;profile=opds-catalog;kind=acquisition",
"rel": "http://opds-spec.org/catalog"
},
{
"href": "https://bplsimplye.bklynlibrary.org/NYBKLYN/authentication_document",
"type": "application/vnd.opds.authentication.v1.0+json"
},
{
"href": "https://www.bklynlibrary.org/",
"type": "text/html",
"rel": "alternate"
},
{
"href": "https://libraryregistry.librarysimplified.org/library/urn:uuid:edef2358-9f6a-4ce6-b64f-9b351ec68ac4/eligibility",
"type": "application/geo+json",
"rel": "http://librarysimplified.org/rel/registry/eligibility"
},
{
"href": "https://libraryregistry.librarysimplified.org/library/urn:uuid:edef2358-9f6a-4ce6-b64f-9b351ec68ac4/focus",
"type": "application/geo+json",
"rel": "http://librarysimplified.org/rel/registry/focus"
},
{
"href": "mailto:askus@bklynlibrary.org",
"rel": "http://librarysimplified.org/rel/designated-agent/copyright"
},
{
"href": "mailto:askus@bklynlibrary.org",
"rel": "help"
}
]
},
]
}
The search endpoint is used to find libraries that are the most appropriate matches for a human-entered search term.
search -- see Section 2 of the OPDS 2.0 spec.
/search{?query,location,stage}
-
query- Required. A human-entered search query, as defined by the OPDS 2.0 spec. -
location- Optional. The current location of the human user. As withlocationin the proximity endpoint, the value must be a latitude/longitude pair. -
stage- Optional. The same meaning as in the proximity endpoint.
/search?location=45,-122&query=Springfield/search?location=41,-87&query=springfield&stage=all/search?query=Springfield/search?query=Springfield,%20IL/search?query=chicago/search?query=11106/search?query=texas&stage=all/search?query=springfield%20public%20libary/search?query=bpl&stage=production/search?query=Internet%20Archive/search?query=broward%20county/search?query=jessie%20m%20smith%20memorial/search?query=asdfasdfasdfasdf/search?query=library
The representation is an OPDS 2 feed that uses the custom catalogs role to link to other OPDS servers. You should expect a feed that contains 3-5 entries, though there may be significantly more. The most appropriate matches will be transmitted in a single feed; there is no pagination.
This representation will look very similar to the representation sent by the "nearby libraries" endpoint; only the title will be different.