Resources

Root

The Root resource provides information about all available resources through the API.

Example HTTP Request:
http://api.openods.co.uk/api
Example Response:
HTTP/1.0 200 OK
Content-Type: application/json
{
  "organisations": "http://api.openods.co.uk/api/organisations",
  "role-types": "http://api.openods.co.uk/api/role-types"
}
    
Attributes:
  • organisationsstring - The URL root for Organisation resources
  • role-typesstring - The URL root for Role-Type resources

Info

The Info resource returns metadata about the source ODS data currently being served by the API.

Example HTTP Request:
http://api.openods.co.uk/api/info
Example Response:
HTTP/1.0 200 OK
Content-Type: application/json
{
  "FileCreationDate": "2017-02-15T17:10:00",
  "contentDescription": "HSCOrgRefData_Full_20170215",
  "fileVersion": "2-0-0",
  "importDate": "2017-03-21 15:27:55.298493",
  "publicationDate": "2017-02-15",
  "publicationSeqNo": "1",
  "publicationSource": "HSCIC",
  "publicationType": "Full",
  "recordCount": "179917",
  "primaryRoleScope": [
    {
      "displayname": "PRIMARY CARE TRUST SITE",
      "id": "RO180",
      "name": "PrimaryRoleScope"
    },
    {
      "displayname": "NON-NHS ORGANISATION",
      "id": "RO157",
      "name": "PrimaryRoleScope"
    }
  ]
}
    
Attributes:
  • fileVersionstring - The version of the file containing the source data used to populate to
  • importDatestring - The timestamp representing when the current data was imported into the OpenODS database.
  • publicationDatestring - The publication date of the current data.
  • publicationSeqNostring - The publication sequence number of the current data.
  • publicationTypestring - The publication type of the current data (this will almost always be Full.
  • publicationSourcestring - The source of the data publication, usually the publishing organisation.
  • fileCreationDatestring - The timestamp of when the source XML data file was created.
  • recordCountstring - The number of organisation records in the dataset.
  • contentDescriptionstring - A text description of the dataset.
  • primaryRoleScopestring - A list of PrimaryRole records which represents the scope of the dataset.

Organisations

An Organisation resource is a single organisation within ODS.

Endpoint:
  • /organisationsstring - get all the Organisation resources (will return a list of 'summary' resource records).
  • /organisations/:odsCodestring - get a specific Organisation resource by its ODS code (will return the full resource).
Query Parameters:
  • qstring - Filter results to those containing specified string in their name attribute.
  • offsetinteger - Return results offset by specified number.
  • limitinteger - Limit number of results returned to specified number (maximum 1000).
  • recordClassstring - Filter results by their record class (HSCOrg or HSCSite).
  • roleCodestring - Filter results to only those which have the specified role.
  • primaryRoleCodestring - Filter results to only those which have the specified primary role (ignored if roleCode is also specified).
  • activeboolean - Filter results to only those with a matching active status e.g. True for Active, False for Inactive.
  • lastUpdatedSinceISO8601 date - Filter results to only those records that have been updated since the date specified. Date must be in format lastUpdatedSince=yyyy-mm-dd. Will accept lastUpdatedSince=yyyy-mm or lastUpdatedSince=yyyy.
Endpoint:
  • /organisations/:odsCodestring - get a specific Organisation resource by its ODS code (will return the full resource).
Query Parameters: None
Example HTTP Request:
http://api.openods.co.uk/api/organisations?q=barnsley&limit=10&roleCode=RO197
Example Response:
HTTP/1.0 200 OK
Content-Type: application/json
{
  "organisations": [
    {
      "links": [
        {
          "href": "http://api.openods.co.uk/api/organisations/RFF",
          "rel": "self"
        }
      ],
      "name": "BARNSLEY HOSPITAL NHS FOUNDATION TRUST",
      "odsCode": "RFF",
      "recordClass": "HSCOrg",
      "status": "Active"
    }
  ]
}
        

Example HTTP Request:
http://api.openods.co.uk/api/organisations/RFF
Example Response:
HTTP/1.0 200 OK
Content-Type: application/json

{
  "addresses": [
    {
      "addressLines": [
        "GAWBER ROAD"
      ],
      "country": "ENGLAND",
      "county": "SOUTH YORKSHIRE",
      "postCode": "S75 2EP",
      "town": "BARNSLEY"
    }
  ],
  "lastChanged": "2015-05-26",
  "links": [
    {
      "href": "http://test.openods.co.uk/api/organisations/RFF",
      "rel": "self"
    }
  ],
  "name": "BARNSLEY HOSPITAL NHS FOUNDATION TRUST",
  "odsCode": "RFF",
  "operationalStartDate": "1993-04-01",
  "recordClass": "HSCOrg",
  "refOnly": false,
  "relationships": [
    {
      "code": "RE1",
      "description": "HAS A LEGACY RELATIONSHIP TO",
      "links": [
        {
          "href": "http://test.openods.co.uk/api/organisations/D",
          "rel": "related-organisation"
        }
      ],
      "operationalStartDate": "2004-04-01",
      "relatedOdsCode": "D",
      "relatedOrganisationName": "YORKSHIRE & THE HUMBER GOVERNMENT OFFICE REGION",
      "status": "Active",
      "uniqueId": 417
    },
    {
      "code": "RE1",
      "description": "HAS A LEGACY RELATIONSHIP TO",
      "legalEndDate": "2013-03-31",
      "legalStartDate": "2006-07-01",
      "links": [
        {
          "href": "http://test.openods.co.uk/api/organisations/Q32",
          "rel": "related-organisation"
        }
      ],
      "operationalEndDate": "2014-08-31",
      "operationalStartDate": "2006-07-01",
      "relatedOdsCode": "Q32",
      "relatedOrganisationName": "YORKSHIRE AND THE HUMBER STRATEGIC HEALTH AUTHORITY",
      "status": "Inactive",
      "uniqueId": 51767
    }
  ],
  "roles": [
    {
      "code": "RO57",
      "description": "FOUNDATION TRUST",
      "links": [
        {
          "href": "http://test.openods.co.uk/api/role-types/RO57",
          "rel": "role-type"
        }
      ],
      "operationalStartDate": "2005-01-01",
      "primaryRole": false,
      "status": "Active",
      "uniqueId": 154857
    },
    {
      "code": "RO197",
      "description": "NHS TRUST",
      "links": [
        {
          "href": "http://test.openods.co.uk/api/role-types/RO197",
          "rel": "role-type"
        }
      ],
      "operationalStartDate": "1993-04-01",
      "primaryRole": true,
      "status": "Active",
      "uniqueId": 126697
    }
  ],
  "status": "Active",
  "successors": [
    {
      "links": [
        {
          "href": "http://test.openods.co.uk/api/organisations/CJA",
          "rel": "predecessor"
        }
      ],
      "targetOdsCode": "CJA",
      "targetName": "BARNSLEY ACUTE SERVICES UNIT",
      "targetPrimaryRoleCode": "RO111",
      "type": "Predecessor",
      "uniqueId": 11545
    }
  ]
}
    
Attributes:
  • namestring - The name of this organisation.
  • odsCodestring - The ODS code of this organisation.
  • last_changedstring - The date on which this organisation record was list updated.
  • operationalStartDatestring - The Operational Start Date for this organisation.
  • operationalEndDatestring - The Operational End Date for this organisation.
  • legalStartDatestring - The Legal End Date for this organisation.
  • legalEndDatestring - The Legal End Date for this organisation.
  • recordClassstring - The record class of the organisation - currently either HSCOrg or HSCSite.
  • refOnlyboolean - Whether the record is included just for reference (will soon be moved to archived data).
  • statusstring - The status of this organisation record - either Active or Inactive
  • addressesarray - An array of address objects related to this organisation record.
  • relationshipsarray - An array of relationship objects related to this organisation record.
  • rolesarray - An array of role objects related to this organisation record.
  • successorsarray - An array of successor objects related to this organisation record.
  • linksarray - An array of hypermedia links relevant to this resource.