We've made it easy to explore marine mammal sighting data.

We receive thousands of public sighting reports each year, and make it available to numerous research, education and management projects all over the world. We've now made it even easier to integrate with, analyze and visualize Hotline sighting data* via our API.

Usage Requirements

By using this API you agree to give The Whale Museum full acknowledgement as the data source through citation where the data are used on any and all products.

Looking for ideas?

The pie chart on this page, our Hotline map interface and our whale sighting counters all use our API as a data source. If you are working on an integration with our API, we'd love to hear about it! Please send us an email at so we can share your work with others.

*Only a subset of our Hotline sighting data is exposed via our API. Since we use a map interface, only sightings with reliable location information are exposed.

Endpoints

Making requests to the Hotline API.

Simply make http requests to http://hotline.whalemuseum.org with the appropriate endpoint path. Only GET requests are currenlty supported. All data is returned in JSON format.

GET /api.json

Returns an array of sighting reports matching your query.

Returns: Array of JSON objects
Parameters: Yes (see below)

GET /api/count.json

Returns a count of sighting reports matching your query.

Returns: Integer
Parameters: Yes (see below)

GET /api/:id.json

Returns a single sighting report matching the id provided in the request URL.

Returns: JSON
Parameters: No

Request Parameters

Search the Whale Hotline data.

You can include the following request parameters to the /api.json and /api/count.json endpoints to search for specific data:


species

Get sighting reports for a specific marine mammal species. Available options are: orca, minke, gray whale, humpback, atlantic white-sided dolphin, pacific white-sided dolphin, dalls porpoise, harbor porpoise, harbor seal, northern elephant seal, southern elephant seal, california sea Lion, steller sea lion, sea otter, other and unknown

orca_type

Get sighting reports for a particular type of Orca. Provide a comma-separated list of types to include. Available options include: southern resident, northern resident, transient and offshore.
(Ignored unless species is "orca".)

orca_pod

Get sighting reports for a particular pod of Southern Resident Orca. Provide a comma-separated list of types to include. Available options include: j, k and l.
(Ignored unles species is "orca" and orca_type is "southern resident".)

limit

The number of sighting reports to return. This is also used in determining page size when page is provided.
(default: 50) (maximum: 1000)

page

The page number to return. Page size is determined by the limit parameter.
(default: 1)

since

Show sightings that occured after a specific date and time.
(supports natural language dates, such as "yesterday" or "12 hours ago".)

until

Show sightings that occured before a specific date and time.
(supports natural language dates, such as "yesterday" or "12 hours ago".)

near

Show sightings that occured near a center point. Provide a comma-separated Lat/Lng point.
(Ex: near=48.5159,-123.1524)

radius

Show sightings within this radius (in miles) of the center point in miles.
(Ignored unless near is provided. Default: 1)

Examples

All data is returned in JSON format.

Get the 50 most recent Orca sightings:

GET /api.json?species=orca

[
  {
    "id":"1234",
    "species":"Orca",
    "quantity":"20+",
    ...
  },
  ...
]

Get a count of all sightings:

GET /api/count.json

17828

Get a count of all Orca sightings:

GET /api/count.json?species=orca

15594

Get a specific sighting:

GET /api/1234.json

{
  "id":"1234",
  "species":"Orca",
  "quantity":"20+",
  ...
}

Get 1000 recent orca sightings within 0.5 miles of Lime Kiln Lighthouse:

GET /api.json?species=orca&near=48.5159,-123.1524&radius=0.5&limit=1000

[
  {
    "id":"1234",
    "species":"Orca",
    "quantity":"20+",
    ...
  },
  ...
]

Feedback

The Whale Hotline API is new, and we are always looking for ideas and suggestions about how we can make it better. We'd love to hear your feedback about the Whale Hotline and our API.

Please feel free to contact us at .

Want to get involved, stay informed and be engaged?