Feasibility

Feasibility is the process of searching for available boxes at an address to make a new sale. Feasibility is typically conducted using a search standard based on poles (adjacencies), where you first select the pole and then the box. However, it can be set to perform feasibility by radius or manually, as you can see in this tutorial. For sales in condominiums, please refer to this other tutorial.

Below, we will provide examples to teach you how to check the feasibility of a specific address to complete a sale using the OZmap API.

From here, we will assume that you understand the difference between these two feasibility types. If you have any questions, don't hesitate to contact the OZmap support team.

To make it easier to understand, we will create an example scenario.

Initial scenario

According to the example mentioned above, you want to make a new sale and need to check the available boxes that serve the customer in that region, and the sales team from the ERP already has all the necessary data of the new customer, including the address and name of the customer

Example

A customer who wishes to sign a plan with the provider access the portal and contact the provider’s support.

The provider's chatbot will request all the necessary data from the customer to complete the sale since it is a new customer.

After collecting the data, the chatbot will contact OZmap to check the customer feasibility at the address.

Below there's a flow to facilitate the understanding:

Using the information returned by OZmap, the chatbot can decide what to inform the customer.

API

The next step is to determine the feasibility of connecting a customer at a specific address using OZmap. This can be done in two ways:

Feasibility by Radius: Checking availability within a defined radius from given coordinates.
Feasibility by Poles: Identifying the nearest pole and verifying connectivity options from it.

Here is an example:

After identifying the customer as new, we have the customer’s address. For this example, let’s assume the address is: 720 Michigan Avenue, Chicago, IL -- 60605, United States. However, the API only accepts latitude, longitude, and radius, so they must be provided.

To get the latitude and longitude of an address, click on this tutorial.

The latitude and longitude being: 41.87252057124877, -87.62489949084207, and radius: 100, the query to OZmap would be made like this:

Feasibility by radius

curl -X 
GET "https://sandbox.ozmap.com.br:9994/api/v2/ftth-viability/radius?lat=41.87252057124877&lng=-87.62489949084207&radius=100" /
--header 'authorization: AUTHORIZATION_TOKEN'

The expected response for this lat and long is:

{
  "viable": true,
  "boxes": [
      {
          "distance": 30.41,
          "name": "CTO 22-05",
          "id": "5dc06d1275fc7d0006732521",
          "project": "5d51a87046cbe700148328bf",
          "lat": 41.87252057124877,
          "lng": -87.62489949084207,
          "implanted": true,
          "availability": 6,
          "horizontal_condos": []
      }
  ],
  "refused_boxes": [],
  "properties": [
      {
          "id": "6168210a1692a900135b628d",
          "address": "720 Michigan Avenue, Chicago, IL -- 60605, United States",
          "observation": "This property was disconnected when a new client was created in this box. The previous connection for this property, identified as 'SS 22-05 - Port 2,' now belongs to client 38742|217968.",
          "lat": 41.87252057124877,
          "lng": -87.62489949084207,
          "box": "5dc06d1275fc7d0006732521",
          "project": "5d51a87046cbe700148328bf",
          "horizontal_condos": []
      }
  ]
}

Feasibility by poles

Another approach is to determine the feasibility based on the nearest pole. This is done in two steps:

Find the nearest pole to the provided coordinates.
Use that pole ID to check feasibility.

Send a request to search for the closest pole within a 100-meter radius using the coordinates from the address:

curl -X
GET 'https://sandbox.ozmap.com.br:9994/api/v2/poles?filter=[{"property":"coords","operator":"near","value":{"lat":"-41.87252057124877","lng":"-87.62489949084207","radius":100}}]' /
--header 'authorization: AUTHORIZATION_TOKEN'

The expected response is:

{
    "total": 1,
    "count": 1,
    "rows": [
        {
            "poleType": "5d7d2b78dbc425449801709f",
            "adjacents": [
                "5da61d8e493d9c000666541a",
                "5da61d8e493d9c000666541b",
                "5da61d8e493d9c0006665419",
                "5da723ab11450e0006947afb"
            ],
            "usable": true,
            "observation": "",
            "coords": [
                -87.62489949084307,
                -41.87252057124677
            ],
            "kind": "Pole",
            "name": "P_30",
            "createdAt": "2019-10-16T20:10:44.642Z",
            "updatedAt": "2025-01-20T13:48:10.961Z",
            "tags": [],
            "licensing": {
                "status": 0,
                "protocol": "",
                "id": "67d986fb3d5d4dd1df3e9a49"
            },
            "id": "5da7794411450e0006949190",
            "lng": -87.62489949084307,
            "lat": -41.87252057124677
        },
    ],
    "start": 0,
    "limit": 25
}

Now that we have the nearest pole (ID: 5da7794411450e0006949190), we can check the feasibility from this pole using the following request (also passing the coordinates from the address):

curl -X
GET "https://sandbox.ozmap.com.br:9994/api/v2/ftth-viability/pole?pole_id=5da7794411450e0006949190&lat=41.87252057124877&lng=-87.62489949084207" /
--header 'authorization: AUTHORIZATION_TOKEN'

For details on additional query parameters, refer to the OZmap documentation.

The expected response for this lat and long is:

{
  "viable": true,
  "boxes": [
      {
          "distance": 30.41,
          "name": "CTO 22-05",
          "id": "5dc06d1275fc7d0006732521",
          "project": "5d51a87046cbe700148328bf",
          "lat": 41.87252057124877,
          "lng": -87.62489949084207,
          "implanted": true,
          "availability": 6,
          "horizontal_condos": []
      }
  ],
  "refused_boxes": [],
  "properties": [
      {
          "id": "6168210a1692a900135b628d",
          "address": "720 Michigan Avenue, Chicago, IL -- 60605, United States",
          "observation": "This property was disconnected when a new client was created in this box. The previous connection for this property, identified as 'SS 22-05 - Port 2,' now belongs to client 38742|217968.",
          "lat": 41.87252057124877,
          "lng": -87.62489949084207,
          "box": "5dc06d1275fc7d0006732521",
          "project": "5d51a87046cbe700148328bf",
          "horizontal_condos": []
      }
  ]
}

Note that in the response of both examples the viable information is marked as “true”.

With this information, the Chatbot could, for example, give a standard response to the customer, indicating that there's availability to sign up for a plan at their address. If they are interested, they could be directed to contact the provider's sales department or make a reservation using the viable options.