# How to use the findAvailableArea API in v3

**URL:** <https://community.bluescape.com/t/how-to-use-the-findavailablearea-api-in-v3/2135>\
**Category:** Developer\
**Tags:** api\
**Created:** [July 26, 2022, 6:49pm UTC](https://community.bluescape.com/t/how-to-use-the-findavailablearea-api-in-v3/2135 "2022-07-26T18:49:20Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Tom\_Garrett](https://avatars.discourse-cdn.com/v4/letter/t/258eb7/32.png) [@Tom\_Garrett](https://community.bluescape.com/u/Tom_Garrett)\
**Post date:** [July 26, 2022, 6:49pm UTC](https://community.bluescape.com/t/how-to-use-the-findavailablearea-api-in-v3/2135/1 "2022-07-26T18:49:20Z")

</div>

**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](https://community.bluescape.com/t/how-to-use-the-findavailablearea-api-in-v3/2135#use-findavailablearea-rest-apis-1) and for [GraphQL APIs](https://community.bluescape.com/t/how-to-use-the-findavailablearea-api-in-v3/2135#use-findavailablearea-graphql-apis-3). 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:

 ![image](https://us1.discourse-cdn.com/bluescape/original/2X/8/8b95c079d1c02afda24822c24e35c8d162733640.png)

This is an example of the request body:

```auto
{
  "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:

```auto
{
  "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**
>
> ```auto
> 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**
>
> ```auto
> // 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**
>
> ```auto
> # 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:

```auto
{
  "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.

```auto
query findAvailableAreaForNewContent( $workspaceId: String! $proposedArea: BoxInput! $direction: FindAvailableAreaDirection!) {
    findAvailableArea( workspaceId: $workspaceId , proposedArea: $proposedArea, direction: $direction) {
        x y width height
    }
}

```

and use these variables:

```auto
{
    "workspaceId": "<SET_WORKSPACE_ID>",
    "proposedArea" : {
        "height": 1500,
        "width": 3000,
        "x": 100,
        "y": 100
    },
    "direction" : "right"
}

```

## Code sample

> **cURL**
>
> ```auto
> 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**
>
> ```auto
> 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**
>
> ```auto
> 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:

```auto
{
    "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?
> 
> - [Traits: API for elements traits](https://community.bluescape.com/t/traits-api-for-elements-traits/2138)
> - [Bluescape API Guides](https://community.bluescape.com/t/bluescape-api-guides-landing-page/2020)
> - [Bluescape API Overview](https://community.bluescape.com/t/wip-bluescape-api-overview/2021/2)
> - [Latest Developer topics](https://community.bluescape.com/c/developer/14)
> 
> **Not what you were looking for? Reply below or [Search](https://community.bluescape.com/search) the community and discover more Bluescape.**