Introduction
Welcome to the 20Echo API!
We have examples for curl and language bindings in Ruby and Elixir. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl -H "Authorization: your api key" "api_endpoint_here"
require '20e'
api = TwentyEcho::APIClient.new('your api key')
api = TwentyEcho.new(key: "your api key")
20echo uses API keys to allow access to the API. Contact support@20echo.com to discuss obtaining an API key.
20echo expects for the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: your api key
Echoes
Get All Echoes
curl -H "Authorization: your api key" https://api.20echo.com/v1/echoes
require '20e'
api = TwentyEcho::APIClient.new('your api key')
api.echoes.get
api = TwentyEcho.new(key: "your api key")
TwentyEcho.Echo.get(api)
The above command returns JSON structured like this:
{
"total_pages": 1,
"total_entries": 1,
"page_size": 100,
"page_number": 1,
"logs": [
{
"user_id": 1,
"timezone_offset": 0,
"taken_at": "1970-01-01T00:33:36",
"status": "failed",
"share_path": "11a293ca-4ee7-4e55-a9fb-221394451aef",
"name": "Sup",
"long": -90,
"location": "POINT(-90.0 30.0)",
"lat": 30,
"image": "11a293ca-4ee7-4e55-a9fb-221394451aef.jpg",
"id": 1,
"deleted_at": null,
"data": {}
}
]
}
This endpoint retrieves all echoes paginated.
HTTP Request
GET https://api.20echo.com/v1/echoes
Query Parameters
Start and end timestamps are expected to be in ISO 8601 format and in UTC time zone. Example: 2000-01-01 00:00:00
Parameter | Required | Description |
---|---|---|
page | false | Results are paginated so use this to specify which page of results you want for a query |
billfish_members_only | false | If set to true, results will be limited to billfish members |
billfish_member_id | false | If a billfish member id is provided, results will be limited to echoes by that member |
start_timestamp | false | If provided, limits echoes to those taken at that time and later |
end_timestamp | false | If provided, limits echoes to those taken at that time and before |
lat | false | Limit results to echoes taken near a specific latitude and longitude. Only applicable when long is also provided. |
long | false | Limit results to echoes taken near a specific latitude and longitude. Only applicable when lat is also provided. |
radius | false | Radius of the search area around lat and long in meters. Only applicable with lat and long parameters. Default is 10000 |
Get a Specific Echo
curl -H "Authorization: your api key" https://api.20echo.com/v1/echo/1
require '20e'
api = TwentyEcho::APIClient.new('your api key')
api.echoes.get(1)
api = TwentyEcho.new(key: "your api key")
TwentyEcho.Echo.get(api, 1)
The above command returns JSON structured like this:
{
"user_id": 1,
"timezone_offset": 0,
"taken_at": "1970-01-01T00:33:36",
"status": "failed",
"share_path": "11a293ca-4ee7-4e55-a9fb-221394451aef",
"name": "Sup",
"long": -90,
"location": "POINT(-90.0 30.0)",
"lat": 30,
"image": "11a293ca-4ee7-4e55-a9fb-221394451aef.jpg",
"id": 1,
"deleted_at": null,
"data": {}
}
This endpoint retrieves a specific echo.
HTTP Request
GET https://api.20echo.com/echoes/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the echo to retrieve |
Create an echo
curl -H "Authorization: your api key" \
-d "lat=90" \
-d "long=30" \
-d "taken_at=1493071599" \
https://api.20echo.com/v1/echoes
The above command returns JSON structured like this:
{
"success": {
"log": {
"user_id": 1,
"timezone_offset": 0,
"taken_at": "2017-04-24T22:06:39.000Z",
"status": "new",
"share_path": "7afe83e2-6a7b-43ae-9a2e-d55ae0e586ac",
"name": null,
"long": 30,
"location": "POINT (30.0 90.0)",
"lat": 90,
"image": {
"image": {
"url": null
}
},
"id": 5135,
"deleted_at": null,
"data": {}
}
}
}
This endpoint creates an echo based on location and time.
The response will have an empty set of data. The returned id should be used to
poll the API until the status is either done
or failed
. Descriptions of
each status are available below.
HTTP Request
POST https://api.20echo.com/echoes
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
lat | float | Required | Latitude in the range of -90 to 90 |
long | float | Required | Longitude in the range of -180 to 180 |
taken_at | integer | Required | Timestamp as a UNIX timestamp integer |
Echo Statuses
Echoes can have the following statuses:
Status | Meaning |
---|---|
new | The echo was just created. It takes time for our robot army to collect the data you are looking for. |
queueing | We are currently fetching data for this echo. |
done | Data has been collected successfully! |
failed | Some (or all) data has been collected unsuccessfully! |
Errors
This API uses the following error codes:
Error Code | Meaning |
---|---|
401 | Unauthorized – Your API key is invalid |
404 | Not Found – The specified resource could not be found |
429 | Too Many Requests – You are making requests too quickly |
500 | Internal Server Error – We had a problem with our server. Try again later. |
503 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |