Overview
Play allows you to connect to an external data source and use its data in your project. You can populate your prototypes in Play with the values and content from the selected data source, and, when applicable, you can communicate information back to the data source.
We offer two data source connections: APIs and static dictionary JSON files. We’ll use the Fetch node to explain how to access values using response keys, but the process is the same for both Fetch and Local JSON.
Loading your API or JSON File
The first step to use external data is to load it into Play. APIs are loaded using an interaction node called Fetch, and JSON files are loaded using an interaction node called Fetch JSON.
Depending on which data source you’re using, you’ll add the Fetch node or the Fetch JSON node to a trigger. Check out the Fetch (API) support article and/or the Fetch JSON support article to learn more.
API Note: You can use any API URL with Play’s Fetch node. Each API works differently, so you need to read your selected API’s documentation and add headers accordingly.
Important Note About Using API Keys in Play
If you are using any sensitive API keys in your Fetch nodes, these keys are exposed and can be seen by users of your prototypes and apps.
For prototypes, make sure you have your App Clip's password protected and that you are sending to trusted sources.
For Export to Xcode, we recommend you store your keys server side using services like Firebase Cloud Functions, Supabase Edge Functions, or AWS Lambda for secure request handling.
Accessing the Response
The information you’ll get from an API or dictionary JSON file is called the response. It might look something like this:
"New York City": {
"name": "New York City
"temperature": "22"
"feels_like": "19"
"weather_type": "Snow"
"img_URL": "<https://www.weather.com/winter/light-snow.html"
}
Each label, like “name,” “temperature,” or “feels_like” is called a key. Each key has an associated value. In the dictionary above, the value for the “name” key is “New York City.”
For an API, you’ll call the full response using:
Fetch.response
For a JSON file, you’ll use:
FetchJSON.response
Saving the Response as a Dictionary Variable
We recommend saving the response as a dictionary variable, so you can use it throughout your project and avoid casting the API/JSON response as a dictionary.
A dictionary variable stores the entire API or JSON response with the data structured in key-value pairs. You’ll create a dictionary variable from the Variables Panel.
Once you’ve created your Dictionary variable, you can use a Set Variable action to set the dictionary variable’s value as the API or JSON response. The Set Variable action must be on the Fetch or Fetch JSON node.
Displaying a Value
The real power comes when you use the API response to call specific values into your prototype.
This example uses the Fetch node for APIs, but you could use JSON as well. If you prefer to learn from a video, the same information is covered in this tutorial:
Each API is different, but they will all have several “keys” which are the labels for pieces of data. In the example above, “temperature” is be a key that stores the current temperature for the given city.
To get the data associated with a key, you need to call each level. So, using the example from above, you’d need to call the “New York City” section before you could call the “temperature”. It will look like this:
#weatherAPI.key("New York City").key("temperature")
To populate a text element with an API value, you’ll add a Set Text action to the Fetch node that’s value is set to the response key.
Displaying Multiple Values
This example uses the Local JSON node, but you could use Fetch as well.
To populate several text or image elements at the same time, you’ll use a similar process from within a Loop node. Instead of selecting a specific city, for example, you’d use the Loop’s index to loop through each dictionary entry.
Because you’re using a Loop, you’ll need to change both the Target and the Text of the Set Text.
For the Target, Loop.item will target each card, but, because you want to select a text element inside the card, you’ll need to use Child At to select a specific child of the card based on its index. If the text element is the second item in the card, it’s index is 1.
Loop.item.childAt(1)
For the Text value, you’ll use the Loop’s index to cycle through each dictionary (in this example, each city).
#weatherAPI.key(Loop.index).key("temperature")
If you have a stack of cards, each of which has two text elements and an image element, you’ll use the same method to set each text element and the image element.
