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/NCT555555.json
• http://api.lillycoi.com/v1/trials/NCT555555.json&fields=id,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	Encoded using Google Maps
.location.geodata.longitude	.json	ct.gov facility address	float	Encoded using Google Maps
.location.geodata.source	.json	N/A	string	Source of the Geo data (i.e.: Google maps)
.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	Encoded using Google Maps

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