RICOH THETA API Introductory Tutorial Using Free API Testing Tools

[erikrod1]

For using the RICOH THETA camera the first time, it would be best to attach the camera on a tripod first to make sure the camera and lens are secured safely. You can turn on the camera once it’s secured at the side of the camera with the power button.

To test the API I am using Insomnia, which you can get here Download - Insomnia

To get started on using the Camera’s API, it’s best to have two separate network connections on your computer, one connection for your internet usage and browsing, and another connection for the Camera’s wifi network. On the laptop I’m using, I have an Ethernet connection on one network for my internet browsing. I am also using the laptop’s own Wifi to connect to another network which is the RICOH THETA Camera’s network.

In both Screenshots we are connected to REGUS for internet access and THETAYN… to connect to the camera via wifi.

For a quick check to see if you can connect to the camera you can open up your command line and ping the camera at 192.168.1.1

Screenshot above shows a successful connection

Above is an empty environment so you want to make a new request by pressing Ctrl+N

Now Insert http://192.168.1.1/osc/info at the Top and press Send. This is the GET command /osc/info from the RICOH THETA API and the base of the API Command is http://192.168.1.1 for all RICOH THETA cameras.

you should get a response to the right with useful information such as the serialNumber and model.

Inside insomnia you can add more requests, rename requests, add a body to your request, and even generate your request as a curl command.

This is a Screenshot of adding a new request

Above is a screenshot of Renaming the request, and other useful options such as Duplicating, Deleting, and Copy as Curl which exports the current request as a curl command which you can get to by right clicking.

Screenshot above shows the option to Copy your request as Curl.

Then as shown above, open your command line and just paste into it and you should get an API response with Curl automatically generated from Insomnia.

Another useful API command is the POST State command from https://github.com/ricohapi/theta-api-specs/blob/main/theta-web-api-v2.1/protocols/state.md

It’s useful because you can check the latest image taken from the Camera by clicking on the link for _latestFileURL.

In insomnia here are the steps:

1. Create a new Request
2. Rename it to anything like “State Command”
3. Change the Request type to POST at the top as shown in the screenshot above
4. Enter the Base URL of the API which is http://192.168.1.1 and the state request command /osc/state
5. Try testing it out by manually taking a picture with the RICOH THETA camera
6. Send in the new request http://192.168.1.1/osc/state
7. Click on the link for _latestFileURL and you should see your latest image taken!

Now this is how to take a picture with the RICOH THETA API on your computer!

We are going to use the POST execute command from https://github.com/ricohapi/theta-api-specs/blob/main/theta-web-api-v2.1/protocols/commands_execute.md

Here are the steps:

1. Create a new Request
2. Rename it to something like “Take Pic”
3. Change the Request type to POST
4. Enter the API command http://192.168.1.1/osc/commands/execute
5. Change the Body type to JSON

6. Inside the JSON body type in the required “name” of the command to execute which for this example is camera.takePicture taken from the API command list as shown in the first screenshot above

7. Send the Command and your camera will take a picture!

[craig]

Thanks for including the links to the specific API commands. RICOH changed the site where the API are and developers are still getting used to the new location.

I’m curious to see if all the curl commands work on the windows command prompt. I’ve sometimes had to use WSL to run the curl commands on my windows 11 laptop.

with WSL

with Windows Command Prompt

You may want to use WSL instead of the Windows command prompt if you have problems with pasting multiple lines into the Windows command prompt.

[jcasman]

@erikrod1 Please consider adding closeups of the Insomnia screenshots. Often the response section, on the right, is small and hard to read.

Thanks very much for adding arrows and numbering to point out certain actions (how build new API requests), that is better than just a static screenshot.