Finding businesses around

In this tutorial we will show you an example using our API, inspired by the use case of one of our real customers.

We want to provide a representative of a food business with a list of companies in the catering sector (restaurants, canteens, bars, etc ..) located a short distance from its location.

Useful Resources

Let’s start

The Location Search API offers both the ability to sort by business locations at a distance and to set the distance from a point within which to search.

We suppose our agent is in the center of Trento (latitude and longitude 46.067351, 11.121325). We therefore seek the Ateco sector of our potential customers using the dedicated endpoint:

https://api.atoka.io/v2/ateco?query=ristorazione&token=TOKEN

{  
    "items": [
        {
            "code": "56",
            "description": "attività dei servizi di ristorazione",
            "rootCode": "I"
        }, 
        /*omitted*/
    ]
}

Now we can search companies in this area within 500 meters from the given point:

https://api.atoka.io/v2/locations?packages=base&companyAteco=56&lat=46.067351&lon=11.121325&distance=500&ordering=distance&token=TOKEN

{
    "meta": {
        "limit": 10,
        "count": 245,
        "ordering": "distance"
    },
    "items": [
        {
            "id": "5413314b4546",
            "base": { 
                "address": {
                    "distance": 28,
                    /* ... */ 
                },
                "company": { 
                    "legalName": "GROMART S.R.L.",
                    "id": "893c134733c8"
                }, 
                /* ... */ 
            }
        },
        /* ... */
    ]
}

We searched for business locations:

in the catering sector (companyAteco=56);
within 500 meters (distance=500);
around the center of Trento (lat=46.067351 lon=11.121325); and
sorted by distance from a specific point (ordering=distance).

We can also use other filters to refine our search as registered to only get those with legal headquarters nearby, or even filters on other company based information.

However, if our agent requires a more complex query involving company features not contained in site filters, the Company Search API can help.

Suppose we want to limit the previous search to companies born in the last year.
We use endpoint companies with the same lat, lon and distance parameters to define the starting point and radius, ordering = distance to sort results, ateco = 56 for the industry and add ageMax=12 to filter companies born in the last 12 months. We also include the parameter anyAddress = true to consider all locations and not just the registered office.

https://api.atoka.io/v2/companies?packages=base,locations&lat=46.067351&lon=11.121325&distance=500&ordering=distance&anyAddress=true&ageMax=12&token=TOKEN

{
    "meta": {
        "limit": 10,
        "count": 10,
        "ordering": "distance"
    },
    "items": [
        {
            "id": "84b3ce2fa0ce",
            "name": "FAES EMANUELE",
            "base": { 
                "registeredAddress": {
                    "distance": 92,
                    /* ... */ 
                },
                /* ... */ 
            },
            "locations": { 
                "items": [{  /* lista di indirizzi di eventuali altre sedi */
                    "address": { 
                        "distance": 210312,  /* distanza per ogni indirizzo */
                        /* ... */
                    }
                }],
                /* ... */ 
            }
        },
        ...
    ]
}

By following the same procedure and by using the APIs with the ‘fields=facets’ parameter in a very similar way, you can analyze and segment the surrounding businesses, by Ateco sector, by turnover or other dimensions.

Alternatively, given a company with many branches spread across the Italian territory it is possible to have the one closest to us. For example, look for the closest post office to Piazza Duomo (assuming you know the Atoka ID of Poste Italiane):

https://api.atoka.io/v2/locations?companies=9302c2d7719f&ordering=distance&lat=46.067351&lon=11.121325&packages=base&distance=10000&limit=1&token=TOKEN

How much does it cost?

In this tutorial we used the Locations endpoint, which provides us data about the companies local units, and therefore consumes credits of type locations:*: similarly to companies, each local unit we get in the results (with at least one data package) will consume one credit.

Atoka Trick

If we don’t care at first showing all the companies on the map, we can save some credit with this trick. When we look for companies around us, we can avoid using the packages parameter: we’ll have all the results ordered by distance from the closest to the furthest, but we won’t be able to see all the details about their position. When our agent chooses the company he wants to visit first, we can show it on the map by asking the details of that local unit (identified by the id):

// costs 0 credits
https://api.atoka.io/v2/locations?companyAteco=56&lat=46.067351&lon=11.121325&distance=500&ordering=distance&token=TOKEN

// costs 1 credit
https://api.atoka.io/v2/locations?ids=<id>&packages=*&token=TOKEN