The Amazon Echo API

 

I love my Amazon Echo! But what else can I do with it?

First of all, I’m not a web developer, so go easy on me, but also help me out by being constructive. I’m an Automation Engineer, that is, I design electrical and control systems for manufacturing machines and then program the PLCs, and I write C# interfaces to the machines. I also did some embedded work and some website programming a long time ago, but anything after 2000 is new to me. But I guess that just makes it more exciting!

echo app

When I use the web-based control app at echo.amazon.com I can use Google Chrome to watch the network activity. Here’s a list of URLs that my browser hits with responses, with identifying stuff filtered out with “xxx”. I have a cookie set with a session ID, which is probably being used to get my user-specific information.

https://pitangui.amazon.com/api/check-client-version?version=v1.2-174-gcadbe83

(no response)

https://pitangui.amazon.com/api/devices/device

{"devices":[{"accountName":"xxx's Echo","deviceAccountId":"xxx","deviceOwnerCustomerId":"xxx","deviceType":"AB72C64C86AW2","online":true,"postalCode":null,"registrationId":null,"serialNumber":"xxx","softwareVersion":"2100"}]}

https://pitangui.amazon.com/api/todos?type=TASK&size=1

{"values":[{"complete":false,"createdDate":1418360739053,"customerId":"xxx","deleted":false,"itemId":"A94B0T49AALEW#3de6b833-3f38-3290-b98d-8f6c6d582246","lastLocalUpdatedDate":null,"lastUpdatedDate":1418360739053,"nbestItems":["roast beef","beef","roast groceries","groceries","brush beef"],"originalAudioId":"AB72C64C86AW2:1.0/2014/12/12/05/B0F00712447601DB/05:34::TNIH_2V.f34eec6a-82b3-4841-b68d-f3336830b454ZXV/1","text":"roast beef","type":"TASK","version":1}]}

[I was trying to say “brush teeth” :)]

https://pitangui.amazon.com/api/cards?limit=3

{"cards":[{"cardType":"StandardCard","creationTimestamp":1418424998722,"deleteCardAction":{"actionType":"DeleteCardAction","cardId":"A94B0T49AALEW#1418424998722","mainText":"Remove card","subText":"Learn more","subTextRoute":"help/node/201602230"},"descriptiveText":null,"giveFeedbackAction":{"actionType":"NavigateAction","mainText":"Thank you! Your feedback helps Echo understand you better.","musicCustomerId":null,"route":"beta-feedback","serviceName":null,"subText":"Send more detailed feedback.","subTextRoute":null},"id":"A94B0T49AALEW#1418424998722","imageAction":{"actionType":"PlayItAgainAction","mainText":"Radio Disney","queueCustomerId":"A94B0T49AALEW","queueId":"1f1ce0db-a300-4d1c-abf4-9b019caf6882","subText":null,"subTextRoute":null},"imageCaption":null,"imageReference":{"deviceSerialNumber":"B0F00712447601DB","deviceType":"AB72C64C86AW2","fallbackIcon":"TUNE_IN","referenceId":"1f1ce0db-a300-4d1c-abf4-9b019caf6882:1","referenceType":"MusicReferenceIdImageReference"},"nBestOptions":[],"playbackAudioAction":{"actionType":"PlayAudioAction","mainText":"Echo heard: \"i heart radio\"","subText":null,"subTextRoute":null,"url":"/api/utterance/audio/data?id=AB72C64C86AW2:1.0/2014/12/12/22/B0F00712447601DB/56:35::TNIH_2V.44b8e078-8eda-4c7f-ac8a-cc94684347deZXV/1"},"primaryActions":[{"actionType":"NavigateAction","mainText":"Browse your TuneIn stations","musicCustomerId":null,"route":"music/TUNE_IN","serviceName":null,"subText":null,"subTextRoute":null}],"registeredCustomerId":"A94B0T49AALEW","secondaryActions":null,"sourceDevice":{"serialNumber":"B0F00712447601DB","type":"AB72C64C86AW2"},"subtitle":"Live station on TuneIn","thumbsUpDownActivityAction":{"actionType":"ThumbsUpDownActivityAction","activityId":"A94B0T49AALEW#1418424998722","mainText":"Did Echo hear you correctly?","subText":null,"subTextRoute":null},"title":"Radio Disney","wrapTitle":false}]}

https://pitangui.amazon.com/api/media/provider-capabilities

{"providerCapabilities":{"ADVERTISEMENT":{"canCreateStation":false,"canJump":false,"canNext":false,"canNextAtEndOfQueue":false,"canPlay":true,"canPrevious":false,"canRepeatAll":false,"canScanContent":false,"canShuffle":false,"canThumbsDown":false,"canThumbsUp":false,"queueModifiedInPlace":false}
...and so on

https://pitangui.amazon.com/api/bluetooth

{"bluetoothStates":[{"deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","online":true,"sconeBattery":85,"sconePaired":true,"softwareVersion":"2100","streamingState":null}]}

https://pitangui.amazon.com/api/customer-status/

{"eulaAcceptance":true,"hasActiveDopplers":true}

https://pitangui.amazon.com/api/authentication

{"authenticated":true,"canAccessPrimeMusicContent":false,"customerEmail":"xxx","customerId":"xxx","customerName":"Owen Piette"}

https://pitangui.amazon.com/api/album-art/1f1ce0db-a300-4d1c-abf4-9b019caf6882:1?deviceSerialNumber=xxx&deviceType=AB72C64C86AW2&screenWidth=1920

https://pitangui.amazon.com/api/music-account-details

That’s it. Later I’ll see if I can match these API queries against the JavaScript so I can make a more complete list of the API. I’m starting to get the idea…

https://pitangui.amazon.com/api/notifications

{"notifications":[{"alarmTime":1418513400000,"deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","id":"xxx-B0F00712447601DB-a1","notificationIndex":"a1","remainingTime":0,"status":"OFF","triggerTime":0,"type":"Alarm","version":"26"},{"alarmTime":0,"deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","id":"xxx-B0F00712447601DB-t1","notificationIndex":"t1","remainingTime":0,"status":"OFF","triggerTime":0,"type":"Timer","version":"28"}]}

https://pitangui.amazon.com/api/third-party

{"services":[{"associationState":"UNASSOCIATED","serviceName":"I_HEART_RADIO","username":null},{"associationState":"UNASSOCIATED","serviceName":"TUNE_IN","username":null}]}

https://pitangui.amazon.com/api/device-preferences

{"devicePreferences":[{"autocastToThisClient":false,"deviceAccountId":"xxx","deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","postalCode":"52201","responseStyle":"CONCISE","searchCustomerId":"xxx","temperatureScale":"FAHRENHEIT","voiceCastEnabled":true}]}

And so on!

Here’s one that I guessed:¬†https://pitangui.amazon.com/api/wake-word

{"wakeWords":[{"deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","wakeWord":"ALEXA"}]}

I want to modify that value! I guess tomorrow.

-Owen

8 thoughts on “The Amazon Echo API

  1. Pingback: Home Automation With The Amazon Echo | Hackaday

  2. Pingback: Home Automation With The Amazon Echo | Ad Pub

    • @Chris Until Amazon opens up the wake word to other options we’ll have to stick with what we have. I tried changing the value in the PUT req but unfortunately their API rejects it.

  3. Looks like forum registration is currently disabled.. Dug through the JS a bit and wanted to share a few findings:

    – The microphone array can apparently determine where the Echo is located based on acoustics… very cool: KEY_DISTANCE_BETWEEN_DEVICE_AND_WALL, KEY_IS_DEVICE_IN_CORNER
    – Internal phrasing is interesting: doppler = wifi setup mode, scone = remote (turns out it is bluetooth), earcon = before / after request audio cues
    – References for collections of devices within the household.. purely speculation but Amazon may have Sonos in the crosshairs.

  4. Pingback: Amazon Artwork Api | Smiling Experts

Leave a Reply

Your email address will not be published. Required fields are marked *