Ready Signal API Documentation

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,            "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            },            "status": "Ready",            "error_message": ""        }   ], }

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,        "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"        },        "status": "Ready",        "error_message": ""    } }

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” and “Day” time grains, 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:

1. You can track the status from the Dashboard;
2. A email is send by Ready Signal when processing is complete;
3. Verify by API the status processing using My Signal Details endpoint;
4. 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.

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
	date_grain	“Day” or “Month” | Required | Date Grain type
	create_custom_features	“0” or “1” | Optional | Numeric
	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}

5.1 POST Array Input

Send a array of objects to process Auto Discovery.

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",     "date_grain": "Month",     "create_custom_features": 1,     "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
	date_grain	“Day” or “Month” | Required | Date Grain type
	create_custom_features	“0” or “1” | Required | Numeric
	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 date_grain: Day Input create_custom_features: 1 Input file: my-value-file.csv

Response

{     "message": "Your signal has been created",     "signal_id": 1235 }