(Quick Reference)

Match

Bibliographic data to BL record matching can be accessed at /match using HTTP GET

Description

The Match operation provides an advanced search like function to search the British Library's remote supply collection. Matching requires a set of Bibliographic data relating to the item we are trying to find. The operation returns a match status of either:

  1. HIGH MATCH - whereby there is a single item that the Api has deemed the correct item.
  2. POSSIBLE MATCH - whereby the Api could not determine an exact match and hence a list of possible records is returned.
  3. NO MATCH - where no records could be found that resemble the supplied data.

Where there is a HIGH MATCH or POSSIBLE MATCH, the matched item(s) details are returned. Further information about the matched item(s) can also be returned if optional parameters are supplied to the operation.

If the MatchRequest.includeAvailability parameter is passed as true and authentication information is provided via an Authentication Request then the availability information will be customer specific. If not then the availability will be the default availability for the item.

Parameters

  • MatchRequest.BibData - the Bibliographic data of the item we are matching. The parameter format is detailed below.

The Bibliographic data to be supplied is of course dependent and applicable to the item type (e.g. a conference venue is not applicable to a book). Possible parameters that can be supplied are:

  • MatchRequest.BibData.type - the material type of the item (journal, book, article etc) - This is NOT Mandatory and can be one of the following: book, journal, article, newspaper, conference, thesis, score
  • MatchRequest.BibData.titleLevel.title - the Title level title (Journal title, Book title)
  • MatchRequest.BibData.titleLevel.author - the Title level author
  • MatchRequest.BibData.titleLevel.ISBN - the ISBN
  • MatchRequest.BibData.titleLevel.ISSN - the ISSN
  • MatchRequest.BibData.titleLevel.ISMN - the ISMN
  • MatchRequest.BibData.titleLevel.shelfmark - the shelfmark
  • MatchRequest.BibData.titleLevel.publisher - the publisher
  • MatchRequest.BibData.titleLevel.conferenceVenue - the conference venue
  • MatchRequest.BibData.titleLevel.conferenceDate - the conference date
  • MatchRequest.BibData.titleLevel.thesisUniversity - the thesis university
  • MatchRequest.BibData.titleLevel.thesisDissertation - the thesis dissertation title
  • MatchRequest.BibData.titleLevel.mapScale - the map scale
  • MatchRequest.BibData.itemLevel.year - the year
  • MatchRequest.BibData.itemLevel.volume - the volume
  • MatchRequest.BibData.itemLevel.part - the part
  • MatchRequest.BibData.itemLevel.issue - the issue
  • MatchRequest.BibData.itemLevel.edition - the edition
  • MatchRequest.BibData.itemLevel.season - the season
  • MatchRequest.BibData.itemLevel.month - the month
  • MatchRequest.BibData.itemLevel.day - the day
  • MatchRequest.BibData.itemLevel.specialIssue - the special issue
  • MatchRequest.BibData.itemOfInterestLevel.title - the item of interest level title (e.g. article title)
  • MatchRequest.BibData.itemOfInterestLevel.pages - the item of interest level pages
  • MatchRequest.BibData.itemOfInterestLevel.author - the item of interest level author (e.g. article author)

Optional Parameters

  • MatchRequest.includeRecordDetails - whether to include record details for records matched, or simply the record ID's. Default is false.
  • MatchRequest.includeAvailability - whether to include Availability for any HIGH MATCH records found. Default is false. If true then MatchRequest.includeRecordDetails will default to true as well.
  • MatchRequest.fullDetails - whether to return the full record details (e.g. the Abstract if one exists) for each matched record when used in conjunction with MatchRequest.includeRecordDetails. Default is false.
  • MatchRequest.highMatchOnly - whether to only return HIGH MATCH records or to provide POSSIBLE MATCH records where they exist. Default is false.
  • MatchRequest.maxResults - the maximum number of POSSIBLE MATCH records to return where a HIGH MATCH is not found (limited to a maximum of 100). Default is 10.

Examples

  • http://api.bldss.bl.uk/api/match?MatchRequest.BibData.type=journal&MatchRequest.BibData.titleLevel.title=Water - search for a Journal whose title is Water
  • http://api.bldss.bl.uk/api/match?MatchRequest.BibData.type=journal&MatchRequest.BibData.titleLevel.title=Water&MatchRequest.includeRecordDetails=true - search for a Journal whose title is Water and include the matched record details in the response

Response

The API call response will be returned as XML. All API calls follow a set format (refer to Output)

A full XML schema will be available at a later date.

The response structure for match call results is as follows:

<apiResponse>
	<timestamp></timestamp>
	<status></status>
	<message/>
	<result>
		<matchStatus>POSSIBLE_MATCH</matchStatus>
		<matches>
			<match>BLL01013467263</match>
			<match>BLL01015485662</match>
			<match>BLL01013089733</match>
		</matches>
	</result>
</apiResponse>

If the MatchRequest.includeRecordDetails flag is passed as true then each match result will be returned as a full record representation in the same way a Search result is represented e.g.

<apiResponse>
	<timestamp></timestamp>
	<status></status>
	<message/>
	<result>
		<matchStatus>HIGH_MATCH</matchStatus>
		<matches>
			<match>
				<uin>BLL01007808049</uin>
				<type>book</type>
				<isAvailableImmediateley>false</isAvailableImmediateley>
				<metadata>
					<titleLevel>
						<title>Oman : water.</title>
						<identifier>System number&nbsp;007808049</identifier>
						<publisher>Great Britain, Overseas Trade Services, 1995.</publisher>
					</titleLevel>
					<itemLevel>
						<year>1995</year>
					</itemLevel>
					<itemOfInterestLevel/>
				</metadata>
			</match>
		</matches>
	</result>
</apiResponse>

If the MatchRequest.includeAvailability flag is passed as true and a HIGH MATCH result is found, then it will be returned as a full record representation (i.e. the MatchRequest.includeRecordDetails flag is explicitly set as true) as well as an additional section detailing the availability for that matched item with relevant pricing information. e.g.

<apiResponse>
	<timestamp></timestamp>
	<status></status>
	<message/>
	<result>
		<matchStatus>HIGH_MATCH</matchStatus>
		<matches>
			<match>
				<uin>BLL01013467263</uin>
				<type>journal</type>
				<isAvailableImmediateley>false</isAvailableImmediateley>
				<date>1963</date>
				<metadata>
					<titleLevel>
						<title>Ground water [electronic resource]</title>
						<identifier>ISSN&nbsp;1745-6584; System number&nbsp;013467263</identifier>
						<issn>1745-6584</issn>
						<publisher>
						Oxford : Blackwell Publishing; [S.l.] : Wiley-Blackwell
						</publisher>
					</titleLevel>
					<itemLevel/>
					<itemOfInterestLevel/>
				</metadata>
				<availability>
					<loanAvailabilityDate>2013-05-24</loanAvailabilityDate>
					<copyAvailabilityDate>2013-05-24</copyAvailabilityDate>
					<copyrightFee currency="GBP">10.5</copyrightFee>
					<availableImmediately>false</availableImmediately>
					<matchedToSpecificItem>false</matchedToSpecificItem>
					<isOnOrder>false</isOnOrder>
					<availableFormats>
						<availableFormat availabilityDate="2013-05-24">
							<deliveryFormat key="1">Encrypted Download</deliveryFormat>
							<deliveryModifiers/>
							<availableSpeeds>
								<speed key="2">2 Hours</speed>
								<speed key="3">24 Hours</speed>
								<speed key="4">4 Days</speed>
							</availableSpeeds>
							<availableQuality>
								<quality key="1">Standard</quality>
								<quality key="2">High</quality>
							</availableQuality>
						</availableFormat>
						<availableFormat availabilityDate="2013-05-24">
							<deliveryFormat key="4">Paper</deliveryFormat>
							<deliveryModifiers/>
							<availableSpeeds>
								<speed key="2">2 Hours</speed>
								<speed key="3">24 Hours</speed>
								<speed key="4">4 Days</speed>
							</availableSpeeds>
							<availableQuality>
								<quality key="1">Standard</quality>
								<quality key="2">High</quality>
							</availableQuality>
						</availableFormat>
					</availableFormats>
				</availability>
			</match>
		</matches>
	</result>
</apiResponse>

Status Codes

These are the following status codes the match operation may return. These are limited to Match specific codes, for general codes refer to Output:

CodeMeaning
102No matches found