getNearbyLocations

POST public/getNearbyLocations

Returns your company's locations near a point, with each location's distance from that point. For example, a technician's tool can use it to find the site they're standing at.

Request syntax

curl https://apiv2.acumera.net/public/getNearbyLocations \
  --cookie av_session.txt \
  --data-urlencode "latitude=<latitude>" \
  --data-urlencode "longitude=<longitude>" \
  [--data-urlencode "max_distance=<miles>"] \
  [--data-urlencode "min_locations=<count>"] \
  [--data-urlencode "active=<active|inactive|all>"] \
  [--data-urlencode "return_brand_images=1"]

Optional parameters are shown in brackets. The username, password, and tfa_token parameters are also accepted, and are required only if the client hasn't already signed in with login. See Getting started with the SC//AcuVigil API.

Request parameters

The request accepts the following parameters in a form-encoded body.

Parameter	Type	Description	Required	Default value
`latitude`	Number	The latitude of the point to search from, in decimal degrees.	Yes
`longitude`	Number	The longitude of the point to search from, in decimal degrees.	Yes
`max_distance`	Number	The search radius, in miles.	No	`128`
`min_locations`	Integer	The minimum number of locations to return. The search returns at least this many locations, even if some are farther than `max_distance`.	No	`3`
`active`	String	Which locations to return: `active`, `inactive`, or `all`. Any other value returns all locations.	No	`all`
`return_brand_images`	Integer	Set to `1` to also return the brand logo images used by the returned locations.	No	`0`

Response syntax

{
    "success": "string",
    "data": {
        "locations": [
            {
                "id": "string",
                "site_name": "string",
                "brand": "string",
                "brand_image": "string",
                "site_description": "string",
                "company_code": "string",
                "company_name": "string",
                "custom_id": "string",
                "serial_number": ["string"],
                "address_line1": "string",
                "city": "string",
                "state": "string",
                "zip": "string",
                "country": "string",
                "latitude": "string",
                "longitude": "string",
                "tz": "string",
                "distance": "string",
                "...": "..."
            }
        ],
        "brand_images": [
            {
                "filename": "string",
                "content_length": number,
                "content_type": "string",
                "image_content": "string"
            }
        ]
    }
}

Response parameters

If the call succeeds, success is "1" and the following data is returned. The main fields are described below; see the example for the full list.

Field	Description
`locations`	The locations found.
`id`	The location ID.
`site_name`, `site_description`	The location's name and description.
`brand`, `brand_image`	The location's brand and the filename of its brand logo, if set.
`company_code`, `company_name`	The location's company.
`custom_id`	Your own ID for the location, if set.
`serial_number`	The serial numbers of the location's ESDs.
`address_line1`, `address_line2`, `city`, `state`, `zip`, `country`	The location's address.
`latitude`, `longitude`	The location's coordinates.
`tz`	The location's time zone, for example `America/Chicago`.
`main_phone`	The location's main phone number, if set.
`primary_carrier`, `secondary_carrier`	The location's internet providers.
`open_24_hours`, `lab_site`, `pilot_site`, `unmonitored`	`"1"` if the location is open 24 hours, is a lab site, is a pilot site, or isn't monitored. Otherwise `"0"`.
`distance`	The location's distance from the point you sent, in miles.
`brand_images`	Only with `return_brand_images=1`: the logo images for the brands of the returned locations, each with `filename`, `content_length` (bytes), `content_type`, and base64-encoded `image_content`.

Errors

If the call fails, success is "0", and returnCode and returnMessage describe the problem. The HTTP status is still 200.

Return code	Message	Cause
`NO_LATITUDE`	The latitude coordinate is missing.	`latitude` is missing or isn't a number.
`NO_LONGITUDE`	The longitude coordinate is missing.	`longitude` is missing or isn't a number.
`NO_LOCATIONS_FOUND`	No locations found.	None of your company's locations match the search.
`INVALID_LOGIN`	We were unable to log you in. Make sure you entered the correct username, password and 2FA code.	You haven't signed in, your session has ended, or the credentials sent with the call are wrong.

Examples

Example: Find locations near a point

This example finds locations within 128 miles of downtown Austin, Texas, returning at least three.

curl https://apiv2.acumera.net/public/getNearbyLocations \
  --cookie av_session.txt \
  --data-urlencode "latitude=30.2672" \
  --data-urlencode "longitude=-97.7431" \
  --data-urlencode "max_distance=128" \
  --data-urlencode "min_locations=3" \
  --data-urlencode "active=all"

Response (shortened to one location):

{
    "success": "1",
    "data": {
        "locations": [
            {
                "id": "4511",
                "site_name": "Store 102",
                "brand": "",
                "brand_image": "",
                "ordered": "0",
                "unbilled": "0",
                "lab_site": "1",
                "unmonitored": "0",
                "pilot_site": "0",
                "site_description": "Store 102",
                "site_notes": "",
                "company_code": "exmpl",
                "company_name": "Example Company",
                "custom_id": "",
                "serial_number": [
                    "0041ac000005"
                ],
                "address_line1": "100 Main St",
                "address_line2": "",
                "city": "Austin",
                "state": "TX",
                "zip": "78701",
                "country": "US",
                "latitude": "30.2672100",
                "longitude": "-97.7431200",
                "tz": "America/Chicago",
                "main_phone": "",
                "toolchains": [
                    "scallion",
                    "tomato"
                ],
                "primary_carrier": "Example Broadband",
                "secondary_carrier": "Example Broadband",
                "open_24_hours": "0",
                "distance": "0.0033722793065328"
            }
        ]
    }
}

Example: Leave out the longitude

{
    "success": "0",
    "returnCode": "NO_LONGITUDE",
    "returnMessage": "The longitude coordinate is missing."
}