Waved APIDevelopers API

Get Started!

Step 0 - Create Your Account

If you have not done so already the first thing you need to do is to create a developers account.

Create Account

You must have an account before continuing!

Create Account

Step 1 - Get Venue  Authorization

A Venue is any location that uses Waved, a Hotel, Cafe, Retail Store, or Restaurant!
Venues usually consosts of many Zones from which you can pull data or send commands through the API!

Before you can fetch data and do your magic, you must be authorized and approved by the Venue!
You do this by asking them for their Venue Conection Code which they can find in the Waved App under Settings → Venue Information → Venue Connection Code

This part is no-code

During development and for testing use this as a venue_connection_code:

AJS-NWX-C26

Step 2 - Get your Tokens!

Once you have the venue_connection_code of a Venue, you can use this along with your client_id and client_secret to get an access token.

Press the "Show Credentials" button to include your client_id and client_secret in the cURL snippit. These can also be found under "Client" in the main menu.

This access-token "links" you to the venue and will grant you access to all endpoints related to this Venue and its Zones

cURL

Use the following request to get an access token:


curl -X POST https://api3.waved.co/api/v1/auth/token \
-H 'Content-Type: application/json' \
-H 'client_id: YOUR-CLIENT-ID' \
-H 'client_secret: YOUR-CLIENT-SECRET' \
-d'{ "venue_connection_code": "AJS-NWX-C26" }'

Successfull response:


{
    token: "YOUR-ACCESS-TOKEN",
    token_type: "Bearer",
    active: true,
    venue: {
        name: "Venue Name"                      <string>
        address: "Venue Address"                <string>
        timezone: "Venue Timezone"              <string>
    }
}

Step 3 - Get Zone Info!

Once you have your token, you can use this to get information about the zones in the venue.

Each zone has a unique id, a name, and a group id. The group id is used to group zones together.

Live data and data trends are fetched on a zone basis and you need to use the zone_id to fetch data and send commands to the zone


IMPORTANT!

It is necesarry to store the zone_ids localy to use for later, it is not recommended to fetch the zone_ids for each call.

This is to reduce the number of calls to the API and to reduce the load on our server.

We do use rate-limiting and calls made to /venue/some_endpoint are highly weighted because the information from these endpoints are mostly static.

So to ensure that you are not limited please store your zone_ids to fetch live data and rolling trends.

cURL

Use the following request to fetch the zones of a venue:


curl -X GET https://api3.waved.co/api/v1/data/zones \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR-TOKEN' \
-d '{}'

Example of successfull response:


{
    number_of_zones: 2,                         <integer>
    automated_zones: 1                          <integer>
    zones: [
        {
            zone_id: "11ksb47h90af",            <string>
            zone_name: "Zone 1",                <string>
            automated: true,                    <boolean>
            group: {
                group_id: "5f6e99b714ff",       <string>
                group_name: "Group 1"           <string>
            }
        }, 
        {
            zone_id: "7d39kdb4705k",            <string>
            zone_name: "Zone 2",                <string>
            automated: false,                   <boolean>
            group: {
                group_id: "nf93dldf20kw",       <string>
                group_name: "Group 2"           <string>
            }
        }
    ]
}

Step 4 - Get Live Data!

Next step is to get live data from a zone. This data is updated frequently and contains information about the current state of the zone. Live data includes information about the current mood, music volume, automation status, and more.

Use the zone_id to get the live data from a specific zone.

About The Response

Meta

  • zone_id, zone_name, automation_is_on, and timestamp:
    • Basic metadata for the zone and data.

Mood

  • index:
    • A 1–10 scale indicating the zone/venue ambience.
  • tag:
    • A descriptive term for the mood index. See documentation for details.

Vibe

  • level:
    • A -2 to 2 scale that let's Waved users put emphasis on music or not (-2 = background, 2 = foreground).
  • label:
    • A descriptive term for the vibe level. Options: 'Ambient', 'Soft', 'Balanced', 'Focused', 'Prevalent'.

Music

  • level:
    • A 0–100 scale when automation is on; can exceed 100 if automation is off.
  • automation, muted, source:
    • Properties of the music object, generally self-explanatory.

cURL

Use the following request fetch live data:


curl -X GET https://api3.waved.co/api/v1/data/zones/ZONE-ID/live \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR-TOKEN' \
-d '{}'

Example of successfull response:


zone_data: {
    zone_id: "11ksb47h90af",                        <string>
    zone_name: "Restaurant",                        <string>
    automation_is_on: true,                         <boolean>
    timestamp: "2024-05-04T13:37:00Z",              <string>
    mood: {
        index: 7,                                   <integer>
        tag: "Vibrant"                              <string>
    };
    vibe: {
        level: 0,                                   <integer>
        label: "Balanced"                           <string>
    };
    music: {
        level: 69,                                  <integer>
        automation: "ON",                           <string>
        muted: false                                <boolean>
        source: {
            source_id: "52k8hd7214ff",              <string>
            name: "Music Player"                    <string>;
        }
    };
    error?: "Only present if there is an error"     <string>
}