Objective: Show how to use the findAvailableArea API in v3.
This page contains the implementation details for the use of the findAvailableArea API, for v3 REST APIs and for GraphQL APIs. This functionality is not implemented for v2 APIs.
When using APIs, how do I know if the (x,y) coordinates I chose for locating an element is empty or if there is content already there (without analyzing the position, height and width of all the elements in the workspace)? The findAvailableArea API searches a workspace for an open area based on the Box provided as input, and the specified direction for this search.
The image below is an example of finding available area to the right of the proposed area:
This is an example of the request body:
{
"direction": "Right",
"proposedArea": {
"height": 1500,
"width": 3000,
"x": 100,
"y": 100
}
}
When executed, the API will search for empty space starting at the position (100, 100), for an Area of 3000 pixels wide and 1500 pixels high. The search will be conducted from the starting position, moving in the specified direction: Right.
The response will contain the coordinates (x,y) that has an empty space for the Box area specified in the request body. Because the specified direction was Right, the response body will maintain the "y" coordinate. The search for empty space was performed by a horizontal movement to the right. Example of the response:
{
"height": 1500,
"width": 3000,
"x": 1950,
"y": 100
}
In the response body, you get the coordinates of where you can start adding your new content: (1950, 100), being sure that there will not be content in a box of 3000 pixels wide and 1500 pixels high, there will be no elements that your new content will overlap over.
Use findAvailableArea, REST APIs
| REST API | /v3/workspaces/<workspaceId>/findAvailableArea |
|---|---|
| Method | POST |
| Comments |
Code sample
cURL
curl --location --request POST 'https://api.apps.us.bluescape.com/v3/workspaces/<SET_WORKSPACE_ID>/findAvailableArea' \
--header 'Authorization: Bearer <SET_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"direction": "Right",
"proposedArea": {
"height": 1500,
"width": 3000,
"x": 100,
"y": 100
}
}'
Node.js
// Node.js Javascript
/*
How to run:
node this_script_name.js
Requires "axios" module (0.19.0), run:
npm install axios
website: https://github.com/axios/axios
*/
var axios = require('axios');
const token = '<SET_TOKEN>';
const portal = 'https://api.apps.us.bluescape.com';
const workspaceId = '<SET_WORKSPACE_ID>';
const api_version = 'v3';
const api_endpoint = `/workspaces/${workspaceId}/findAvailableArea';
const proposedArea = {
"direction": "Right",
"proposedArea": {
"height": 1500,
"width": 3000,
"x": 100,
"y": 100
}
}
var request_values = {
url: `${portal}/${api_version}${api_endpoint}`,
method : 'POST' ,
headers : {
'Authorization': "Bearer " + token,
'Content-Type' : 'application/json'
},
json: proposedArea
};
axios(request_values)
.then(function (response) {
if (response.status == 200)
{
console.log("Success");
console.log(response.data);
}
})
.catch (function (error) {
console.log('Error: ' + error.message);
});
Python
# Python Code (python 3.5+)
import requests
import pprint
'''
Required modules:
requests 2.22.0
'''
token = '<SET_TOKEN>'
if __name__ == "__main__":
portal = "https://api.apps.us.bluescape.com"
workspaceId = '<SET_WORKSPACE_ID>'
API_version = 'v3'
# Get all the images from a workspace
API_endpoint = f'/{API_version}/workspaces/{workspaceId}/findAvailableArea'
proposedArea = {
"direction": "Right",
"proposedArea": {
"height": 1500,
"width": 3000,
"x": 100,
"y": 100
}
}
the_request = requests.post(
portal + API_endpoint,
headers={"Authorization": "Bearer " + token,
"Content-Type": "application/json"
},
json = proposedArea
)
json_response = the_request.json()
pprint.pprint(json_response)
Example of the response from REST:
{
"height": 1500,
"width": 3000,
"x": 1950,
"y": 100
}
In the response body, you get the coordinates of where you can start adding your new content: (1950, 100), being sure that there will not be content in a box of 3000 pixels wide and 1500 pixels high, there will be no elements that your new content will overlap over.
Use findAvailableArea, GraphQL APIs
In GraphQL you can run the findAvailableArea query. Please note that the values for direction must be in lowercase.
query findAvailableAreaForNewContent( $workspaceId: String! $proposedArea: BoxInput! $direction: FindAvailableAreaDirection!) {
findAvailableArea( workspaceId: $workspaceId , proposedArea: $proposedArea, direction: $direction) {
x y width height
}
}
and use these variables:
{
"workspaceId": "<SET_WORKSPACE_ID>",
"proposedArea" : {
"height": 1500,
"width": 3000,
"x": 100,
"y": 100
},
"direction" : "right"
}
Code sample
cURL
curl --location --request POST 'https://api.apps.us.bluescape.com/v3/graphql' \
--header 'Authorization: Bearer <SET_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query findAvailableAreaForNewContent( $workspaceId: String! $proposedArea: BoxInput! $direction: FindAvailableAreaDirection!) {\n findAvailableArea( workspaceId: $workspaceId , proposedArea: $proposedArea, direction: $direction) {\n x y width height\n }\n\n\n\n}","variables":{"workspaceId":"<SET_WORKSPACE_ID>","proposedArea":{"height":1500,"width":3000,"x":100,"y":100},"direction":"<SET_DIRECTION>"}}'
Node.js
const axios = require('axios');
const url = "https://api.apps.us.bluescape.com/v3/graphql"
const token = "<SET_TOKEN>"
const query =
`query findAvailableAreaForNewContent( $workspaceId: String! $proposedArea: BoxInput! $direction: FindAvailableAreaDirection!) {
findAvailableArea( workspaceId: $workspaceId , proposedArea: $proposedArea, direction: $direction) {
x y width height
}
}`
const variables = {
"workspaceId": "<SET_WORKSPACE_ID>",
"proposedArea" : {
"height": 1500,
"width": 3000,
"x": 100,
"y": 100
},
"direction" : "<SET_DIRECTION>"
}
const findAvailableAreaForNewContent = async () => {
try {
const response = await axios.post(url,
{
query: query,
variables: variables
},
{headers: {"Authorization": "Bearer " + token}})
answerData = JSON.stringify(response.data);
console.log(answerData);
return response
}
catch(error) {
console.error(error)
}
}
findAvailableAreaForNewContent();
Python
import requests
import pprint
'''
Required modules:
requests 2.22.0
'''
url = "https://api.apps.us.bluescape.com/v3/graphql"
token = "<SET_TOKEN>"
query = """
query findAvailableAreaForNewContent( $workspaceId: String! $proposedArea: BoxInput! $direction: FindAvailableAreaDirection!) {
findAvailableArea( workspaceId: $workspaceId , proposedArea: $proposedArea, direction: $direction) {
x y width height
}
}
"""
variables = {
"workspaceId": "<SET_WORKSPACE_ID>",
"proposedArea" : {
"height": 1500,
"width": 3000,
"x": 100,
"y": 100
},
"direction" : "<SET_DIRECTION>"
}
def makeQuery():
response = requests.post(url,
headers={"Authorization": "Bearer " + token
},
json={
'query': query,
'variables': variables
})
return response.json()
if __name__ == "__main__":
response = makeQuery()
pprint.pprint(response)
Example of the response from GraphQL:
{
"data": {
"findAvailableArea": {
"x": 1950,
"y": 100,
"width": 3000,
"height": 1500
}
}
}
In the response body, you get the coordinates of where you can start adding your new content: (1950, 100), being sure that there will not be content in a box of 3000 pixels wide and 1500 pixels high, there will be no elements that your new content will overlap over.
Where to Next?
Not what you were looking for? Reply below or Search the community and discover more Bluescape.