Launch Library Reading API Overview

Calls

  • All API calls should be made with HTTP GET.
  • Request data is passed in one of two ways:
    1. An ID or name can be passed in via the URL line. For example /launch/5 or launch/Falcon.
    2. Via URL Parameters, as listed below.
  • Many URL Parameters can be repeated to provide a list. For example /launch?id=4&id=9
  • Text searching is case insensitive.
  • Omitting parameters for each type will usually return a list of 10 objects, but not always. Sometimes it will be more (or all in the case of types), sometimes it will error and tell you what is necessary.
  • Getting 403s? You might need to make sure you are passing in proper headers, such as an accept header and acceptable user agent. Rule of thumb is that if a url is working in a browser, but not your application, you may need to modify your request to make it work.

Returns


  • All returns are JSON objects with various options. The data on non-failure will be variable depending on your options. Failures will contain a status variable and a msg variable:

Failure

Name Description
status "fail"
msg A probably less than helpful error message.

Agency

* Launch Service Providers are agencies with the islsp flag set to 1. As noted below, there is a shortcut to just pull them.

Usage: https://launchlibrary.net/1.3/agency

Usage shortcut for LSPs only: https://launchlibrary.net/1.3/lsp

Examples:

  • To return the agency with an ID of 5:
    https://launchlibrary.net/1.3/agency/5
    OR
    https://launchlibrary.net/1.3/agency?id=5
  • To return the agency with an abbreviation of NASA:
    https://launchlibrary.net/1.3/agency/NASA
    OR
    https://launchlibrary.net/1.3/agency?abbrev=nasa
  • NOTE: Agencies match here against abbreviation, not name.
  • To return the agency with a name matching "National":
    https://launchlibrary.net/1.3/agency?name=National

All Parameters:

NameDescription
modeHow much you want returned. Either list, summary, or verbose.
idThe id of a specific agency you want.
nameThe name of a specific agency you want.
abbrevThe abbreviaton of the agency you want.
typeThe agency type id for the agency you are looking for.
countryCodeThe three letter country code the agency's country of origin.
islspWhether or not this agency is a Launch Service Provider.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
abbrevStringLSV
typeIntegerSV
countryCodeStringSV
wikiURLStringV
infoURL*StringV
infoURLsArray of stringsV
islspInteger (0 for no, 1 for yes)V
*The property infoURL is being depricated and will be removed in future releases, please switch your applications to using infoURLs

Agency Type

Usage: https://launchlibrary.net/1.3/agencytype

Examples:

  • To return the agency type with an ID of 1:
    https://launchlibrary.net/1.3/agencytype/1
    OR
    https://launchlibrary.net/1.3/agencytype?id=1
  • To return the agency type with a name of government:
    https://launchlibrary.net/1.3/agencytype/Government
    OR
    https://launchlibrary.net/1.3/agencytype?name=Government

All Parameters:

NameDescription
nameName for the agency type.
idID for the agency type.

Returned Properties:

NameType
idInteger
nameString

Event Type

Usage: https://launchlibrary.net/1.3/eventtype

Examples:

  • To return the event type with an ID of 1:
    https://launchlibrary.net/1.3/eventtype/1
    OR
    https://launchlibrary.net/1.3/eventtype?id=1
  • To return the event type with a name of info:
    https://launchlibrary.net/1.3/eventtype/info
    OR
    https://launchlibrary.net/1.3/eventtype?name=info

All Parameters:

NameDescription
nameName for the event type.
idID for the event type.

Returned Properties:

NameType
idInteger
nameString

Launch

Usage: https://launchlibrary.net/1.3/launch

Note: /calendar is an alias for /launch and sets format=ics for you.

Examples:

  • To return the launch with an ID of 1:
    https://launchlibrary.net/1.3/launch/120
    OR
    https://launchlibrary.net/1.3/launch?id=120
  • To return the launch with a name including Falcon:
    https://launchlibrary.net/1.3/launch/Falcon
    OR
    https://launchlibrary.net/1.3/launch?name=falcon
  • To return the next 5 launches:
    https://launchlibrary.net/1.3/launch/next/5
    OR
    https://launchlibrary.net/1.3/launch?next=5
  • To return launches between August 20th, 2015 and September 20th, 2015:
    https://launchlibrary.net/1.3/launch/2015-08-20/2015-09-20
    OR
    https://launchlibrary.net/1.3/launch?startdate=2015-08-20&enddate=2015-09-20
  • To return launches after August 20th, 2015:
    https://launchlibrary.net/1.3/launch/2015-08-20
    OR
    https://launchlibrary.net/1.3/launch?startdate=2015-08-20
  • To return the launch with the id of 20 and the fields name and location id only:
    https://launchlibrary.net/1.3/launch/20?fields=name,locationid
    OR
    https://launchlibrary.net/1.3/launch?id=20&fields=name,locationid
  • To return the launch with the id of 20 in ICS format:
    https://launchlibrary.net/1.3/launch/20?format=ics
    OR
    https://launchlibrary.net/1.3/calendar/20

Note: The total in the response is the total number of launches meeting your criteria, to be used with paging. You can get the next page by changing your offset.

All Parameters:

NameDescription
modeModes are list, summary, verbose.
sortSorts by NET. Use asc for ascending, desc for descending. Defaults to ascending.
formatFormat of the response. Possible formats are json and ics, defaults to json.
If there is an error or no launches match your criteria, it will respond with a 404 and a json body.
seqUsed only when format=ics. Pass in a sequence number. If it is greater than 0 and they have the event on their calendar, it should update the existing instead of creating a new.

Search Options


If all of the following are omitted, it will return the next 10 launches by default.

nextReturn the next N launches
startdateDate/Time to start search for. If this an
enddateDate/Time for the next launch attempt.
limitLimit of responses. Defaults to 10.
offsetOffset, for pagination.
idThe ID of the launch you are searching for.
nameThe ID of the launch you are searching for.
locationidThe LocationID for the launch you are searching for.
rocketidThe RocketID for the launch you are searching for.
lspThe Launch Service Provider (LSP) agency for the launch

Returned Properties:

NameTypemode(s)
Top Level
offsetInteger (used in paging)LSV
countInteger (used in paging)LV
totalInteger (used in paging)LSV
Launch Objects in Array
idIntegerLSV
nameStringLSV
netString (formatted as Month, dd, yyyy hh24:mi:ss UTC)LSV
tbddateInteger (If it's a 1, we're not 100% on the date)LSV
tbdtimeInteger (If it's a 1, we're not 100% on the time)LSV
statusInteger (1 Green, 2 Red, 3 Success, 4 Failed)SV
inholdInteger (deprecated, use status)SV
windowstartString (formatted as Month, dd, yyyy hh24:mi:ss UTC)SV
windowendString (formatted as Month, dd, yyyy hh24:mi:ss UTC)V
isostartString (formatted as yyyymmddThh24missZ)V
isoendString (formatted as yyyymmddThh24missZ)V
isonetString (formatted as yyyymmddThh24missZ)V
wsstampInteger (Unix timestamp)V
westampInteger (Unix timestamp)V
netstampInteger (Unix timestamp)V
infoURL *StringV
vidURL *StringV
infoURLsArray of stringsV
vidURLsArray of stringsV
holdreasonStringV
failreasonStringV
probabilityInteger (will be -1 if unkown to us)V
hashtagStringV
lspIntegerV
location +An object containing an array of pad objectsV
rocket +Object containing rocket propertiesV
missions +Array containing mission objectsV

* The properties infoURL and vidURL are being depricated and will be removed in future releases, please switch your applications to using infoURLs and vidURLs

+ The various objects returned may not have all of the properties of the verbose objects in their calls.


Launch Event

Usage: https://launchlibrary.net/1.3/launchevent

Examples:

  • To return the launch event with an ID of 7:
    https://launchlibrary.net/1.3/launchevent/7
    OR
    https://launchlibrary.net/1.3/launchevent?id=7
  • To return the launch event with a launch id of 12:
    https://launchlibrary.net/1.3/launchevent?parentid=12

All Parameters:

NameDescription
modeModes are: list, summary, verbose
idID for the launch event.
nameName of launch event
typeEvent type.
parentidID of launch.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
relativeTimeInteger (time in seconds to/from T-0)LSV
typeIntegerSV
durationIntegerSV
descriptionStringV
parentidIntegerV

Launch Status

Usage: https://launchlibrary.net/1.3/launchstatus

Examples:

  • To return the launc status with an ID of 1:
    https://launchlibrary.net/1.3/launchstatus/1
    OR
    https://launchlibrary.net/1.3/launchstatus?id=1
  • To return the launch status with a name of GREEN:
    https://launchlibrary.net/1.3/launchstatus/green
    OR
    https://launchlibrary.net/1.3/launch?name=green

All Parameters:

NameDescription
nameName for the launch status.
idID for the launch status.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
descriptionStringLSV

Location

Usage: https://launchlibrary.net/1.3/location

Examples:

  • To return the location with an ID of 1:
    https://launchlibrary.net/1.3/location/1
    OR
    https://launchlibrary.net/1.3/location?id=1
  • To return the location with a name of Woomera:
    https://launchlibrary.net/1.3/location/woomera
    OR
    https://launchlibrary.net/1.3/location?name=woomera
  • To return the location withing the United States:
    https://launchlibrary.net/1.3/location?countryCode=USA

All Parameters:

NameDescription
modeModes are list, summary, verbose
countrycodeISO 3-letter country code for primary country of the location.
idID of the location.
nameName of the location.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
countrycodeStringLSV
wikiURLStringV
infoURL *StringV
infoURLsArray of stringsV

Mission

Usage: https://launchlibrary.net/1.3/mission

Examples:

  • To return the mission with an ID of 42:
    https://launchlibrary.net/1.3/mission/42
    OR
    https://launchlibrary.net/1.3/mission?id=42
  • To return the mission with a name of GPS:
    https://launchlibrary.net/1.3/mission/GPS
    OR
    https://launchlibrary.net/1.3/mission?name=GPS
  • To return the mission with a launch ID of 12:
    https://launchlibrary.net/1.3/launch?launchid=12

All Parameters:

NameDescription
modeModes are overview, summary, verbose.
fieldsAn array of strings for fields returned in summary or verbose. The ID, name, net, inhold, and status fields are returned in summary if this is not present. All fields are returned in verbose if this is not present.

Search Options


If all of the following are omitted, it will return the first 10 missions returned by the db by default.

limitLimit of responses. Defaults to 10.
offsetOffset, for pagination.
idThe ID of the mission you are searching for.
nameThe ID of the mission you are searching for.
descriptionThe description of the mission you are searching for.
launchidThe ID of the launch the mission is attached to.
typeThe type of mission.
agencyAn agency involved in the mission.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
descriptionStringSV
launchIntegerV
typeIntegerV
wikiURLStringV
infoURL *StringV
infoURLsArray of stringsV
agenciesarray of agenciesV
eventsarray of mission eventsV

Mission Event

Usage: https://launchlibrary.net/1.3/missionevent

Examples:

  • To return the mission event with an ID of 3:
    https://launchlibrary.net/1.3/missionevent/3
    OR
    https://launchlibrary.net/1.3/missionevent?id=3
  • To return the mission event with a mission id of 120:
    https://launchlibrary.net/1.3/missionevent?parentid=120

All Parameters:

NameDescription
modeModes are: list, summary, verbose
idID for the mission event.
nameName of mission event
typeEvent type.
parentidID of mission.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
relativeTimeInteger (time in seconds to/from T-0)LSV
typeIntegerSV
durationIntegerSV
descriptionStringV
parentidIntegerV

Mission Type

Usage: https://launchlibrary.net/1.3/missiontype

Examples:

  • To return the mission type with an ID of 1:
    https://launchlibrary.net/1.3/missiontype/1
    OR
    https://launchlibrary.net/1.3/missiontype?id=1
  • To return the mission type with a name of planetary:
    https://launchlibrary.net/1.3/missiontype/planetary
    OR
    https://launchlibrary.net/1.3/missiontype?name=planetary

All Parameters:

NameDescription
nameName for the mission type.
descriptionA description for the mission type.

Returned Properties:

NameType
idInteger
nameString

Pad

Usage: https://launchlibrary.net/1.3/pad

Examples:

  • To return the pad with an ID of 1:
    https://launchlibrary.net/1.3/pad/1
    OR
    https://launchlibrary.net/1.3/pad?id=1
  • To return pads with a name containing launch complex:
    https://launchlibrary.net/1.3/pad/launch%20complex
    OR
    https://launchlibrary.net/1.3/pad?name=launch%20complex
  • To return pads with a location ID of 5:
    https://launchlibrary.net/1.3/pad?locationid=5

All Parameters:

NameDescription
modeModes are: list, summary, verbose
idThe ID of the pad.
nameName for the pad.
locationidThe ID of the location for the pad.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
padTypeInteger (0 for launch, 1 for landing)SV
latitudeStringSV
longitudeStringSV
mapURLStringV
retiredIntegerV
locationidIntegerV
agenciesArray of agenciesV
wikiURLStringV
infoURL *StringV
infoURLsArray of stringsV

Rocket

Usage: https://launchlibrary.net/1.3/rocket

Examples:

  • To return the rocket with an ID of 1:
    https://launchlibrary.net/1.3/rocket/1
    OR
    https://launchlibrary.net/1.3/rocket?id=1
  • To return the rocket with a name containing Falcon:
    https://launchlibrary.net/1.3/rocket/falcon
    OR
    https://launchlibrary.net/1.3/rocket?name=falcon
  • To return the rockets with configuration containing v1.3:
    https://launchlibrary.net/1.3/rocket?name=v1.3

All Parameters:

NameDescription
modeModes are list, summary, verbose.
idID for the rocket.
nameName for the rocket.
configurationConfiguration text for the rocket
familyIDThe ID for the rocket family.
NameTypemode(s)
idIntegerLSV
nameStringLSV
defaultPadsString (comma delimited integers)LSV
familyObject of rocket familySV
wikiURLStringV
infoURL *StringV
infoURLsArray of stringsV
imageURL +StringV
imageSizes ++Array of integersV

+ We now host rocket images. All images are either public domain, or permission has been obtained for use by those using the Launch Library. Please set these images to cache, and do not pull them every time. They are saved with different widths, maintaining the aspect ratio of the original image. The url returned in imageURL is the largest image available for that rocket.

++ If you wish to pull a smaller image, select one of the widths from imageSizes, and replace it with the width in imageURl


Rocket Event

Usage: https://launchlibrary.net/1.3/rocketevent

Examples:

  • To return the rocket event with an ID of 10:
    https://launchlibrary.net/1.3/rocketevent/10
    OR
    https://launchlibrary.net/1.3/rocketevent?id=10
  • To return the launch event with a launch id of 1 :
    https://launchlibrary.net/1.3/rocketevent?parentid=1

Note: Rocket Events are for individual rockets only, and are copied to launch events when a rocket is assigned to a launch.

All Parameters:

NameDescription
modeModes are: list, summary, verbose
idID for the rocket event.
nameName of rocket event
typeEvent type.
parentidID of rocket.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
relativeTimeInteger (time in seconds to/from T-0)LSV
typeIntegerSV
durationIntegerSV
descriptionStringV
parentidIntegerV

Rocket Family

Usage: https://launchlibrary.net/1.3/rocketfamily

Examples:

  • To return the rocket family with an ID of 1:
    https://launchlibrary.net/1.3/rocketfamily/1
    OR
    https://launchlibrary.net/1.3/rocketfamily?id=1

All Parameters:

NameDescription
nameName for the rocket family.
agenciesAny agencies for the rocket family.

Returned Properties:

NameTypemode(s)
idIntegerLSV
nameStringLSV
agenciesArray of agenciesV