IT Service Cambridgeshire.net Search RSS Web Service Specification

Transcription

1 IT Service Cambridgeshire.net Search RSS Web Service Specification Version: 1.2 Prepared by: Richard Hall (IT Applications Architect) Last updated: 20 th December 2011 File held in: 1. Purpose This document describes the Search RSS feed used to provide search results to 3 rd Party websites and RSS clients from the Cambridgeshire.net database. Contents 1. Purpose RSS Search Web Service Specification A to Z RSS Web Method Search RSS Web Method

2 2. RSS Search Web Service Specification Technology Interface Protocol Encoding Security Comments Web Service Feed (RSS) HTTP (GET) UTF-8 This service is currently open. Client IP Address Test Client IP Address Live Availability of Live service 24/7 except for service breaks. Availability of Test service Service Breaks Performance Support Where possible these will occur outside of normal working hours. They most regularly occur on Wednesday evenings or Sundays. Systems using this service must fail gracefully if the web service is unavailable or returns with an error. The average response time for a page of search results should be < 5 seconds. 3 rd Party developers should contact their CCC contact in the first instance. The CCC contact will then raise a support call via the CCC Business Support Helpdesk for the attention of the CCC Applications Support Team. 2

3 2.1 A to Z RSS Web Method Technology Page name Purpose Web Service URL: Test Web Service URL: Live Called by Request query string parameters Comments Rss.aspx Returns a list of Records (default is Organisation records) for each letter specified, sorted by name (or modified date if specified). Includes additional filters for consistency with search. Specified 3 rd Party Website s servers and end-user clients Name Description Manda tory Letter The first letter of the Organisation, or number for Organisations starting with a number, or all or leave empty to ignore. Sort The order to sort results in. Use date to sort my modified date in descending order. Default is to sort by title SearchType A comma separated list of table names to limit the search to, or all for all tables. Default type if left empty is Organisation. Available tables for search are: Organisation Gateway Event Course Activity News Location Specifying a location adds a distance attribute to the response. The location can be a Cambridgeshire postcode or a Cambridgeshire place name (spaces are ignored). If no match is found it attempts to match on a place name using a Soundex search. Distance When provided with a Location, will only return results within this distance in kilometres. PageNumber The page index number starting at 1 for the first page of results. Optional, default is 1. PageSize The number of results to return per page. Optional, default is 999 Ipsv Optionally filter results by an IPSV term. Use a comma separated list of integer values (no spaces). Any record matching any of these IDs and all children of that term will be included in the A to Z. A complete list of IPSV terms can be found at Audience Filter by target audience. Valid values are: YoungPeople, OlderPeople, ChildrenAndFamilies SpecialistProvi sion Category Price Day Date QuickDate StartMonth TypeOfStudy Qualification SocialCareSer vice Filters by type of special need (eg. disabled people, learning disability). Applies to Organisation, Activity, Event and Course Optionally filters the results by Category. The list of possible values varies depending on SearchType. Applies to Organisation, Course, Event, Activity and News records only. Specifying for other Optionally filters the results by price. Available value is Free. Optionally filters the results by day of the week (e.g. Tuesday ). Applies to Course and Activity on a specific date. Applies to Event and Activity Format is yyyy-mm-dd (e.g ). on a date relative to the current date. Available values are: Today Next weekend Tomorrow Next 7 days This weekend Filters Course, Event and Activity records by starting Month. Applies to Course, Event and Activity Format is MMMM yyyy (e.g. September 2010 ). Specifying for other record types will return no results. Filters Course records to their type of study. Applies to Course Filters Course records to their Qualification. Applies to Course Filters Organisation records by the type of social care service they provide. 3

4 Response elements <?xml version="1.0" encoding="utf-8"?> <rss version="2.0" xmlns:ccc=" xmlns:event=" xmlns:opensearch=" xmlns:media=" xmlns:georss=" <channel> <title>cambridgeshire.net RSS Feed</title> <link> <description>visit Cambridgeshire.net for information on local voluntary organisations.</description> <language>en-gb</language> <copyright>(c) Cambridgeshire County Council </copyright> <opensearch:totalresults>20</opensearch:totalresults> <opensearch:startindex>1</opensearch:startindex> <opensearch:itemsperpage>30</opensearch:itemsperpage> <item> <title>st Neots - Blue Balloon</title> <description> Junior youth club for years 6 to 9 with specific focus on transition between primary and secondary school. Included is work around anti bullying, confidence building and personal and social development. Come along and collect membership form. </description> <link> <pubdate>mon, 20, Apr :16:42 GMT</pubDate> <georss:point> </georss:point> <category>arts, crafts & exhibitions</category> <category>health & wellbeing</category> <category>leisure & hobbies</category> <category>youth activities</category> </item> <!-- More items --> </channel> </rss> Name Description Data Type Occurrences rss Root element complex 1 channel Cambridgeshire.net channel complex 1 channel/title Static title of feed String channel/link Static link to Cambridgeshire.net String 1 homepage channel/description Static description String 1 channel/language Static language String 1 channel/copyright Static copyright message String 1 opensearch:totalresults Total number of results for search Integer 1 opensearch:startindex Index of first result on this page Integer 1 opensearch:itemsperpage Number of search results in a page Integer 1 item A single search result complex 0 or more item/title Record name / title (e.g. Organisation String 1 name or Activity title) item/description Record description String 1 item/link Link to record on Cambridgeshire.net String 1 item/pubdate The date the record was last modified Date and 1 time georss:point The Latitude and Longitude of the Point 0..1 record s venue item/category The category of the record String 0 or more event:startdate Applies to events only the start date Date 0..1 for an event event:enddate Applies to events only the end date Date 0..1 for an event. For a single day event, this will be the day after the startdate (i.e. a date range includes the startdate but excludes the enddate) event:location Applies to events only the locality of the venue for the event String

5 2.2 Search RSS Web Method Technology Page name Purpose Web Service URL: Test Web Service URL: Live Called by Request query string parameters Comments rss_search.aspx Performs a search on the database and returns a page of results, sorted by relevance. Specified 3 rd Party Websites and end-user clients Name Description Manda tory SearchText A free-text search term SearchType A comma separated list of table names to limit the search to, or all or blank for all tables. Available tables for search are: Organisation Event Activity Gateway Course News Location Specifying a location adds a distance attribute to the response. The location can be a Cambridgeshire postcode or a Cambridgeshire place name (spaces are ignored). If no match is found it attempts to match on a place name using a Soundex search. If no SearchText is provided, all records except courses (unless provided in SearchType) will be returned, sorted by distance from the location. Distance When provided with a Location, will only return results within this distance in kilometres. PageNumber The page index number starting at 1 for the first page of results. Optional, default is 1. PageSize The number of results to return per page. Optional, default is 30 Ipsv Optionally filter results by an IPSV term. Use a comma separated list of integer values (no spaces). Any record matching any of these IDs and all children of that term will be included in the search results. A complete list of IPSV terms can be found at Audience Filter by target audience. Valid values are: YoungPeople, OlderPeople, ChildrenAndFamilies SpecialistPro vision Category Price Day Date QuickDate StartMonth TypeOfStudy Qualification SocialCareS ervice Filters by type of special need (eg. disabled people, learning disability). Applies to Organisation, Activity, Event and Course Optionally filters the results by Category. The list of possible values varies depending on SearchType. Applies to Organisation, Course, Event, Activity and News records only. Specifying for other Optionally filters the results by price. Available value is Free. Optionally filters the results by day of the week (e.g. Tuesday ). Applies to Course and Activity on a specific date. Applies to Event and Activity Format is yyyy-mm-dd (e.g ). on a date relative to the current date. Available values are: Today Tomorrow This weekend Next weekend Next 7 days Filters Course, Event and activity records by starting Month. Applies to Course, Event and Activity Format is MMMM yyyy (e.g. September 2010 ). Specifying for other record types will return no results. Filters Course records to their type of study. Applies to Course Filters Course records to their Qualification. Applies to Course Filters Organisation records by the type of social care service they provide. 5

6 Response elements <?xml version="1.0" encoding="utf-8"?> <rss version="2.0" xmlns:ccc=" xmlns:event=" xmlns:opensearch=" xmlns:media=" xmlns:georss=" <channel> <title>cambridgeshire.net RSS Feed</title> <link> <description>visit Cambridgeshire.net for information on local voluntary organisations.</description> <language>en-gb</language> <copyright>(c) Cambridgeshire County Council </copyright> <opensearch:totalresults>20</opensearch:totalresults> <opensearch:startindex>1</opensearch:startindex> <opensearch:itemsperpage>30</opensearch:itemsperpage> <item> <title>st Neots - Blue Balloon</title> <description> Junior youth club for years 6 to 9 with specific focus on transition between primary and secondary school. Included is work around anti bullying, confidence building and personal and social development. Come along and collect membership form. </description> <link> <pubdate>mon, 20, Apr :16:42 GMT</pubDate> <georss:point> </georss:point> <category>arts, crafts & exhibitions</category> <category>health & wellbeing</category> <category>leisure & hobbies</category> <category>youth activities</category> </item> <!-- More items --> </channel> </rss> Name Description Data Type Occurrences rss Root element complex 1 channel Cambridgeshire.net channel complex 1 channel/title Static title of feed String channel/link Static link to Cambridgeshire.net String 1 homepage channel/description Static description String 1 channel/language Static language String 1 channel/copyright Static copyright message String 1 opensearch:totalresults Total number of results for search Integer 1 opensearch:startindex Index of first result on this page Integer 1 opensearch:itemsperpage Number of search results in a page Integer 1 item A single search result complex 0 or more item/title Record name / title (e.g. Organisation String 1 name or Activity title) item/description Record description String 1 item/link Link to record on Cambridgeshire.net String 1 item/pubdate The date the record was last modified Date and 1 time georss:point The Latitude and Longitude of the Point 0..1 record s venue item/category The category of the record String 0 or more event:startdate Applies to events only the start date Date 0..1 for an event event:enddate Applies to events only the end date Date 0..1 for an event. For a single day event, this will be the day after the startdate (i.e. a date range includes the startdate but excludes the enddate) event:location Applies to events only the locality of the venue for the event Date