Locations API Endpoint Follow

This article describes the uses of the top-level Locations API endpoint.

The Locations Endpoint

The Locations endpoint is used as the top-level endpoint for the Placemarks, Maps, and Asset-beacons endpoints.

The Locations endpoint will return data for the locations to which your token has access, but you may find it more useful to use a specific location ID.

   /api/locations/{location_id}

Related Endpoints

The Locations endpoint is the top level endpoint for the following endpoints:

• beacons
• maps
• placemarks
• search

Locations Detail

Making a request to the Locations endpoint will return details about the location and the location’s organization.

Organization Detail

The organization detail information includes the organization name and ID, when it was created, when it was last modified, and other organization-specific information.

Location Detail

The location detail information includes the location name and ID, when it was created, when it was last modified, and other location-specific information.

It also includes a list of the features that are enabled for the location.

Location detail also includes mapping information, such as the location’s latitude and longitude, its time zone, and the default language.

Locations /search Endpoint

You can use the Locations /search endpoint to search any field in a location or to search on a specific field. If you have an API token, the Search endpoint will return data for all locations for which your account has access.

To search on any field, use:

    /locations/search?q={search string}

To search on a specific field, use:

    /locations/search?q={field name}:{search string}

Locations /beacons Endpoint

You can use the Locations endpoint to get all of the Beacons for a specific location ID.

    /api/locations/{location_id}/beacons

You can get information on a specific Beacon using its MAC.

    /api/locations/{location_id}/beacons/{MAC}

With a specific Beacon’s MAC, you can update or delete specific Beacon information.

Beacon Changesets

Changes made to a Beacon’s state in the Meridian Editor’s Beacons Management tool are sent as changesets to observers that are capable of modifying those Beacons, such as Aruba Sensors and Aruba APs.

Changes are limited to Beacon type (Proximity or Location) and Proximity Beacon power level. All other changes live entirely on the Meridian Editor.

    /api/locations/{location_id}/beacons/{MAC}/changesets

Beacons Field Reference

Here are descriptions of the Beacons API endpoint fields.

created and modified Timestamps for when a Beacon was deployed to a map and when a Beacon’s state was last changed.

mac A Beacon’s MAC.

type Whether a Beacon is location or proximity.

map The map where a Beacon is deployed.

x and y The specific x/y coordinates of the Beacon on a map.

major and minor The Beacon’s major/minor values.

UUID The Beacon’s universal unique identifier.

name The Beacon name. Defined in the Meridian Manager app.

firmware_a_version and firmware_b_version The Beacon firmware version. Some Beacon hardware has a second bank for use when the Beacon firmware is being upgraded.

rssi The Beacon received signal strength indication. One indicator of the Beacon’s transmitting power.

battery_level The Beacon battery level.

txpower Beacon transmission power. See also: rssi.

timestamp The last time the Beacon was observed.

observer The ID of the Beacon’s observer for the most recent timestamp.

managed True or False. Is the Meridian Editor’s Beacons Management feature in use for this Beacon?

location The Beacon’s location ID.

Use the API to Batch Upload Data

You can use the Meridian API to batch upload data using the API for the following endpoints:

/locations/{location_id}/placemarks

To create a batch job, post a list of regular POST data to one of these endpoints.

When you do, the API will return a batch_status_url you can use to check the progress of your batch task.

    {
    "batch_status_url": ".../api/v1/locations/{location_id}/batch/{batch_id}"
    }

The batch_status_url will only return a list of object keys in the return_data field, instead of all of the uploaded data. The object keys are the unique IDs for the data being uploaded. The objects are returned in the order they were uploaded.