Lilly Clinical Open Innovation REST API Reference

This is a reference guide for the Lilly Clinical Open Innovation API (LCOI-API). It is divided into these sections: Getting Started Trial Resource API Requests Topic Catalog API Requests Appendix

Getting Started

Resource Overview

• All resources are accessed using HTTP
• Our server is located at http://api.lillycoi.com
• This document is for Version 1 of the api, which is read-only: http://api.lillycoi.com/v1/
• All responses are formatted as JSON
• Some resources support JSON that is specially formatted for use by the MIT Exhibit application. ClinicalCollections.org is an example Django and JS app that consumes the exhibit format.
• Status codes that any resource may return are listed here: Common Status Codes. Codes that are specific to a resource are listed in the documentation for that resource.
• When making requests to the API server, values that you supply are shown in italics.

Clinical Trial Resources

• The information returned by this resource is sourced from NIH clinicaltrials.gov registry. The data is refreshed daily.
• The responses are augmented with additional data such as geo-spacial location data, and ranges for dates and ages.
• Trials resources can be requested via search, list, or by trial id.
• Each resource has a description, URL, HTTP methods, parameters, formats, authentication, limits, examples, and specific status codes.
• See appendix for details on augmented data added to responses by Lilly COI.

---

/trials

---

---

Description

• This endpoint will return all trials.

Resource URL

http://api.lillycoi.com/v1/trials.{format}

HTTP Methods

• GET

Parameters

limit: (optional, number, default: 10 )

• limits the number of results returned
• example: limit=20

offset: (optional, number, default: 0 )

• determines where to begin getting data
• example: offset=23

fields: (optional, string of comma separated fields names, defaults to all fields)

• the response will be constrained to only the fields listed in this parameter. NOTE: only top-level fields will be targeted.
• see the appendix for a list of fields that can be supplied in this parameter
• example for .json request: fields=id,location

Formats

• .json
• .exhibit

Authentication Required: No

Rate Limit: No Limit

Example Usage

• http://api.lillycoi.com/v1/trials.json
• http://api.lillycoi.com/v1/trials.json?limit=50
• http://api.lillycoi.com/v1/trials.json?offset=20&limit=100
• http://api.lillycoi.com/v1/trials.json?offset=20&limit=100&fields=id,location

---

/trials/{id}

---

---

Description

• This endpoint will return a single trial
• {id} is an NCT identifier from clinicaltrials.gov

Resource URL

http://api.lillycoi.com/v1/trials/{id}.{format}

HTTP Methods

• GET

Parameters

fields: (optional, string of comma separated fields names, defaults to all fields)

• the response will be constrained to only the fields listed in this parameter. NOTE: only top-level fields will be targeted.
• example for .json request: fields=id,location

Formats

• .json
• .exhibit

Authentication Required: No

Rate Limit: No Limit

Example Usage

• http://api.lillycoi.com/v1/trials/NCT00552448.json
• http://api.lillycoi.com/v1/trials/NCT00552448.json?fields=id,overall_status,location

---

/trials/search

---

---

Description

• This endpoint performs a search against trial data. If the provider parameter is passed (i.e.: provider=ctgov), the search is performed on that provider’s servers and returns IDs to get from our database.
• See appendix for details on the clinicaltrials.gov search engine.

Resource URL

http://api.lillycoi.com/v1/trials/search.{format}

HTTP Methods

• GET

Parameters

query: (required, a string query )

• the query to execute on a search provider
• the query syntax is provided in the provider’s query language (See appendix for details on the clinicaltrials.gov search engine.)
• for clinicaltrials.gov, by default only the first 20 results are returned; to get more, include ‘count’ in the query, which represents the maximum number of trials to return from the query
• example: query=cond:spondylitis,recr:open,count:500

provider: (optional, one of: ‘ctgov’, default: ctgov )

• determines which search provider to use
• for this version of the API the clinicaltrials.gov search engine is the only one available
• example: provider=ctgov

fields: (optional, string of comma separated fields names, defaults to all fields)

• the response will be constrained to only the fields listed in this parameter. NOTE: only top-level fields will be targeted.
• example for .json request: fields=id,location

limit: (optional, number, default: 20 )

• limits the number of results returned
• example: limit=30

offset: (optional, number, default: 0 )

• determines where to begin getting data
• example: offset=12

Formats

• .json
• .exhibit

Authentication Required: No

Rate Limit: No Limit

Example Usage

• http://api.lillycoi.com/v1/trials/search.json?query=cond:spondylitis,recr:open,count:500
• http://api.lillycoi.com/v1/trials/search.json?query=cond:spondylitis,recr:open,count:500&fields=id,location
• http://api.lillycoi.com/v1/trials/search.json?query=cond:spondylitis,recr:open,count:500&fields=id,location&offset=30&limit=10

---

Topic Resources

• The Topics resources are cloned from the clinicaltrials.gov Topics taxonomy.
• See http://clinicaltrials.gov/ct2/search/browse

---

/studytopics/categories

---

---

Description

• This endpoint will return the root categories

Resource URL

http://api.lillycoi.com/v1/studytopics/categories.{format}

HTTP Methods

• GET

Parameters

• none

Formats

• .json

Authentication Required: No Rate Limit: No Limit Example Usage

• http://api.lillycoi.com/v1/studytopics/categories

---

/studytopics/categories/{parent_id}

---

---

Description

• This endpoint will return the sub categories of the passed parent category

Resource URL

http://api.lillycoi.com/v1/studytopics/categories/{parent_id}.{format}

HTTP Methods

• GET

Parameters

• none

Formats

• .json

Authentication Required: No Rate Limit: No Limit Example Usage

• http://api.lillycoi.com/v1/studytopics/categories/conditions

---

Appendix

Common Status Codes

Status Code	Description
200	Request succeeded with no error
404	url is not found
500	Request failed with an error

Augmented Data

• We copy data from clinicaltrials.gov into the LCOI repository. We do not modify the values in this data for the .json responses.
• Some data in the .exhibit responses are formatted with html to support layout.
• We augment clinicaltrials.gov data with the following geographic data:

Lilly COI Data	Format	Derived from	Type	Description
.location.geodata.latitude	.json	ct.gov facility address	float	Latitude (city level)
.location.geodata.longitude	.json	ct.gov facility address	float	Longitude (city level)
.location.geodata.original	.json	N/A	string	Data sent to the geo-encoding service
.location.geodata.formatted	.json	N/A	string	formatted version of the “original” field
location_latlong	.exhibit	ct.gov facility address	array of strings	latitude/longitude coordinate (city level)

When we inject CT.gov data into the LCOI repository, the following fields are added or enhanced by LCOI in support of Exhibit facets and views:

.exhibit field	comments
primary_outcomes	formatted w/ HTML by LCOI
pubmed_links	formatted w/ HTML by LCOI
results_links	formatted w/ HTML by LCOI
secondary_outcomes	formatted w/ HTML by LCOI
study_design	CT.gov string converted by LCOI to json array
completion_date_iso8601	added by LCOI when injected to LCOI repository
completion_date_range	added by LCOI when injected to LCOI repository
ctgov_results_link	added by LCOI when injected to LCOI repository
duration_months	added by LCOI when injected to LCOI repository
eligibility_maximum_age_range	added by LCOI when injected to LCOI repository
eligibility_minimum_age_range	added by LCOI when injected to LCOI repository
enrollment_range	added by LCOI when injected to LCOI repository
has_results	added by LCOI when injected to LCOI repository
last_changed_iso8601	added by LCOI when injected to LCOI repository
last_injected	added by LCOI when injected to LCOI repository
location_latlong	added by LCOI when injected to LCOI repository
primary_completion_date_iso8601	added by LCOI when injected to LCOI repository
primary_completion_date_range	added by LCOI when injected to LCOI repository
start_date_iso8601	added by LCOI when injected to LCOI repository
start_date_range	added by LCOI when injected to LCOI repository
type_name	added by LCOI when injected to LCOI repository
start_date_range	added by LCOI at http request time
completion_date_range	added by LCOI at http request time
primary_completion_date_range	added by LCOI at http request time

clinicaltrials.gov Search Engine

• See clinicaltrials.gov/ct2/help/help for explanation of CT.gov’s search engine
• We pass search queries to the CT.gov server. If their service is down, then LCOI API searches will fail as well.
• The API uses a slightly different syntax for search expression. Search terms are separated by comma’s instead of the & sign. Our API uses a colon in place of the = sign. Here is an example illustrating the syntactical differences:
  • CT.gov API: http://clinicaltrials.gov/ct2/results?type=Intr&cond=Albinism
  • LCOI API: http://api.lillycoi.com/v1/trials/search.json?query=type:Intr,cond:Albinism

Top Level Fields

• NIH has a page with definitions for data that we have sourced from their clinicaltrials.gov registry.
• The data returned in trial responses can be constrained to specific top-level fields in .json and .exhibit Trial responses.
• The LCOI .json format mimics the CT.gov XML schema

Here are the top-level fields for the .json format responses:

.json Top-level Fields	Type	Source
acronym	string	CT.gov
arm_group	array	CT.gov
attributes	array	CT.gov
biospec_descr	object	CT.gov
biospec_retention	string	CT.gov
brief_summary	object	CT.gov
brief_title	string	CT.gov
clinical_results	object	CT.gov
completion_date	string	CT.gov
condition	array	CT.gov
condition_browse	object	CT.gov
detailed_description	object	CT.gov
eligibility	object	CT.gov
end_date	string	CT.gov
enrollment	object	CT.gov
firstreceived_date	object	CT.gov
firstreceived_results_date	string	CT.gov
has_expanded_access	string	CT.gov
id	string	CT.gov
id_info	object	CT.gov
intervention	array	CT.gov
intervention_browse	object	CT.gov
is_fda_regulated	string	CT.gov
is_section_801	string	CT.gov
keyword	array	CT.gov
last_injected	string	LCOI
lastchanged_date	object	CT.gov
link	array	CT.gov
location	array	CT.gov
location_countries	object	CT.gov
number_of_arms	string	CT.gov
number_of_groups	string	CT.gov
official_title	string	CT.gov
overall_contact	object	CT.gov
overall_contact_backup	object	CT.gov
overall_official	array	CT.gov
overall_status	string	CT.gov
oversight_info	object	CT.gov
phase	string	CT.gov
primary_completion_date	object	CT.gov
primary_outcome	array	CT.gov
reference	array	CT.gov
removed_countries	object	CT.gov
required_header	object	CT.gov
responsible_party	object	CT.gov
results_reference	array	CT.gov
secondary_outcome	array	CT.gov
source	string	CT.gov
sponsors	object	CT.gov
start_date	object	CT.gov
study_design	string	CT.gov
study_type	string	CT.gov
verification_date	object	CT.gov
why_stopped	string	CT.gov

Here are the top-level fields for the .exhibit format responses:

.exhibit Top-level Fields	Type	Source
acronym	string	CT.gov
alt_link	string	CT.gov
arm_groups	array	CT.gov
biospec_description	string	CT.gov
biospec_retention	string	CT.gov
brief_summary	string	CT.gov
cities	array	CT.gov
collaborators	array	CT.gov
completion_date	string	CT.gov
completion_date_iso8601	string	LCOI
completion_date_range	string	LCOI
completion_date_type	string	CT.gov
condition_mesh_terms	array	CT.gov
conditions	array	CT.gov
countries	array	CT.gov
ctgov_results_link	string	LCOI
detailed_description	string	CT.gov
duration_months	num	LCOI
eligibility_criteria	string	CT.gov
eligibility_gender	string	CT.gov
eligibility_healthy_volunteers	string	CT.gov
eligibility_maximum_age_range	string	LCOI
eligibility_maximum_age_years	num	CT.gov
eligibility_minimum_age_range	string	LCOI
eligibility_minimum_age_years	num	CT.gov
eligibility_sampling_method	string	CT.gov
eligibility_study_population	string	CT.gov
enrollment	num	CT.gov
enrollment_range	string	LCOI
enrollment_type	string	CT.gov
funded_by	string	CT.gov
has_expanded_access	string	CT.gov
has_results	string	CT.gov
has_results	string	LCOI
health_authorities	array	CT.gov
id	string	CT.gov
intervention_mesh_terms	array	CT.gov
intervention_types	array	CT.gov
interventions	array	CT.gov
is_fda_regulated	string	CT.gov
is_section_801	string	CT.gov
keywords	array	CT.gov
label	string	CT.gov
last_changed	string	CT.gov
last_changed_iso8601	string	LCOI
last_injected	string	LCOI
lead_sponsor	string	CT.gov
lead_sponsor	string	CT.gov
location_latlong	array	LCOI
locations	array	CT.gov
nct_id	string	CT.gov
number_of_arms	num	CT.gov
official_title	string	CT.gov
org_study_id	string	CT.gov
overall_contact_backup_email	string	CT.gov
overall_contact_backup_last_name	string	CT.gov
overall_contact_backup_phone	string	CT.gov
overall_contact_backup_phone_extension	string	CT.gov
overall_contact_email	string	CT.gov
overall_contact_last_name	string	CT.gov
overall_contact_phone	string	CT.gov
overall_contact_phone_extension	string	CT.gov
overall_officials	array	CT.gov
overall_status	string	CT.gov
primary_completion_date	string	CT.gov
primary_completion_date_iso8601	string	LCOI
primary_completion_date_range	string	LCOI
primary_completion_date_type	string	CT.gov
primary_measures	array	CT.gov
primary_outcomes	array	CT.gov formatted w/ LCOI HTML
pubmed_links	array	CT.gov formatted w/ LCOI HTML
responsible_party_name_title	string	CT.gov
responsible_party_organization	string	CT.gov
results_links	array	CT.gov formatted w/ LCOI HTML
secondary_id	array	CT.gov
secondary_measures	array	CT.gov
secondary_outcomes	array	CT.gov formatted w/ LCOI HTML
start_date	string	CT.gov
start_date_iso8601	string	LCOI
start_date_range	string	LCOI
states	array	CT.gov
study_design	array	CT.gov string converted by LCOI to array
study_phase	string	CT.gov
study_type	string	CT.gov
type_name	string	LCOI
url	string	CT.gov
why_stopped	string	CT.gov