Instructions on how to use Ready Signal API. Location of API end points, how to get access tokens, how to call API.
Ready Signal API
The Ready Signal API is designed to let you retrieve the processed data from one of your Signals.
Production Endpoint: https://app.readysignal.com/api/
1. Get an Access Token
To access the Ready Signal API, you have to get an access token and send it through your request’s authorization header.
Login to the Ready Signal portal, access the detail page of your Signal or create a new Signal if you don’t have one.
Scroll the page down to the API Credentials section, and use the button next to the Access Token to copy your token.
That’s it. You will use that token to authenticate your next requests.
2. GET My Signals
To get the list of your signals.
Request
GET
/signals
Headers
Accept
application/json
Content-Type
application/json
Authorization
Bearer {token}
Request GET /api/signals HTTP/1.1 Host: app.readysignal.com Content-Type: application/json Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCI1N...bGciOiJSUzI1Nmqhi6A
Response { "data": [ { "id": 48, "name": "My Signal Name", "description": "The description of my signal.", "desired_geo_grain": "State", "desired_time_grain": "Week", "start_at": "01/26/2020", "end_at": "05/31/2020", "created_at": "06/03/2020", "updated_at": "06/03/2020", "deleted_at": null, "company": { "id": 1024, "name": "Ready Signal Team", "plan_id": 1, "plan_value_id": 1, "subscription_status": "active", "created_at": "2020-05-11 18:39:24", "updated_at": "2020-05-11 18:40:22", "need_listining_webhook": 0 }, "user": { "id": 1015, "company_id": 1024, "name": "Marco Tanaka", "email": "marco@example.com", "type": "owner", "created_at": "2020-05-11 18:39:24", "updated_at": "2020-05-11 18:39:24" }, "industry": { "id": 2, "name": "CPG", "created_at": "2020-04-10 23:21:39", "updated_at": "2020-04-10 23:21:39" }, "analysis_type": { "id": 3, "name": "Classification", "created_at": "2020-04-10 23:21:45", "updated_at": "2020-04-10 23:21:45" }, "output": { "json": "https://app.readysignal.com/api/signals/48/output?format=json" }, "links": { "self": "https://app.readysignal.com/signal/48/manage", "manage": "https://app.readysignal.com/signal/48/manage } } ], }
3. GET My Signals Detail
To get the detail of the specified signal.
Request
GET
/signals/{Signal_ID}/
Headers
Accept
application/json
Content-Type
application/json
Authorization
Bearer {token}
Request GET /api/signals/48 HTTP/1.1 Host: app.readysignal.com Content-Type: application/json Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCI1N...bGciOiJSUzI1Nmqhi6A
Response { "data": { "id": 48, "name": "My Signal Name", "description": "The description of my signal.", "desired_geo_grain": "State", "desired_time_grain": "Week", "start_at": "01/26/2020", "end_at": "05/31/2020", "created_at": "06/03/2020", "updated_at": "06/03/2020", "deleted_at": null, "company": { "id": 1024, "name": "Ready Signal Team", "plan_id": 1, "plan_value_id": 1, "subscription_status": "active", "created_at": "2020-05-11 18:39:24", "updated_at": "2020-05-11 18:40:22", "need_listining_webhook": 0 }, "user": { "id": 1015, "company_id": 1024, "name": "Marco Tanaka", "email": "marco@example.com", "email_verified_at": null, "type": "owner", "created_at": "2020-05-11 18:39:24", "updated_at": "2020-05-11 18:39:24" }, "industry": { "id": 2, "name": "CPG", "created_at": "2020-04-10 23:21:39", "updated_at": "2020-04-10 23:21:39" }, "analysis_type": { "id": 3, "name": "Classification", "created_at": "2020-04-10 23:21:45", "updated_at": "2020-04-10 23:21:45" }, "output": { "json": "https://app.readysignal.com/api/signals/48/output?format=json" }, "links": { "self": "https://app.readysignal.com/signal/48/manage", "manage": "https://app.readysignal.com/signal/48/manage" } } }
4. GET My Signal Output
To get the output of the specified signal.
The resulting data is paginated every 1000 records. You can use the “page” query string to get data from other pages. You can also see other pagination metadata on the JSON payload.
Request
GET
/signals/{Signal_ID}/output
Query Strings
Page
Integer | Optional | The number of the pagination page
Headers
Accept
application/json
Content-Type
application/json
Authorization
Bearer {token}
Request GET /api/signals/48/output?page=1 HTTP/1.1 Host: app.readysignal.com Content-Type: application/json Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCI1N...bGciOiJSUzI1Nmqhi6A
Response { "current_page": 1, "data": [ { "start": "2020-01-26", "end": "2020-02-01", "state": "Alabama", "population-rural": "1957932.00000000000000000000" }, { "start": "2020-01-26", "end": "2020-02-01", "state": "Alaska", "population-rural": "241338.00000000000000000000" }, {…}, { "start": "2020-05-24", "end": "2020-05-30", "state": "Puerto Rico", "population-rural": "232533.00000000000000000000" } ], "first_page_url": "https://app.readysignal.com/api/signals/48/output?page=1", "from": 1, "last_page": 1, "last_page_url": "https://app.readysignal.com/api/signals/48/output?page=1", "next_page_url": null, "path": "https://app.readysignal.com/api/signals/48/output", "per_page": 1000, "prev_page_url": null, "to": 936, "total": 936 }
5. Auto Discovery
Ready Signal analyzes your data to identify and recommend external factors like weather, economic, and demographic trends that impact your unique business every day. There are two types of methods to start an Auto Discovery: Array or File . Currently Auto Discovery is working with “Month” time grain only, so all dates must be the first day of each month. Auto Discovery processing is asynchronous.
You have four ways to know when the signal processing has been completed:
You can track the status from the Dashboard; A email is send by Ready Signal when processing is complete; Verify by API the status processing using My Signal Details endpoint; Passing a URL in the callback_url parameter so that Ready Signal can notify your system by send a GET request with parameter signal_id in query string.
5.1 POST Array Input
Send a array of objects to process Auto Discovery.
Request
POST
/auto-discovery/array
Parameters
callback_url
URL | Optional | Callback url when the Auto Discovery process finish
geo_grain
"State" or "Country" | Required | Geo Grain type
data
Array of Data object | Required | An array of data object
Data Object
Date
Date | Required | Default date format "Y-m-01"
Value
Numeric | Required | Numeric value
State
String | Required if geo_grain is "State" | State abreviation (AK, IN)
Headers
Accept
application/json
Content-Type
application/json
Authorization
Bearer {token}
Request POST /api/auto-discovery/array HTTP/1.1 Host: app.readysignal.com Content-Type: application/json Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCI1N...bGciOiJSUzI1Nmqhi6A Body: { "callback_url": "https://my-website.com/my-callback-url", "geo_grain": "State", "data": [ { "Date": "2022-01-01", "State": "AK", "Value": 2654.5 }, { "Date": "2022-02-01", "State": "AK", "Value": 854.2 }, { "Date": "2022-03-01", "State": "AK", "Value": 1786.9 } ] }
Response { "message": "Your signal has been created", "signal_id": 1234 }
5.2 POST File Input
Send a CSV or Excel file to process Auto Discovery. You can download the template file from the Ready Signal App.
Request
POST
/auto-discovery/file
Parameters
callback_url
URL | Optional | Callback url when the Auto Discovery process finish
geo_grain
"State" or "Country" | Required | Geo Grain type
file
CSV or Excel file | Required
Headers
Accept
application/json
Authorization
Bearer {token}
Request POST /api/auto-discovery/file HTTP/1.1 Host: app.readysignal.com Content-Type: application/json Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCI1N...bGciOiJSUzI1Nmqhi6A Input callback_url: https://my-website.com/my-callback-url Input geo_grain: Country Input file: my-value-file.csv
Response { "message": "Your signal has been created", "signal_id": 1235 }