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,
           "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:

  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.

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
}