Locations API Endpoint

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}

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

  • beacons
  • campaigns
  • events
  • feeds
  • 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 Aruba Beacons 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.

Locations /campaigns Endpoint

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

    /api/locations/{location_id}/campaigns

Campaigns Field Reference

Here are descriptions of the Campaigns API endpoint fields.

created and modified Timestamps for when a campaign was created and when it was last modified.

always_broadcast True or False. When True, the campaign will always trigger. When False, it will be limited by date and time.

allday True or False. When always_broadcast is False, you can limit the campaign to specific dates. If you do, you can set the campaign to trigger for the entire 24 hours on the specified dates.

dtstart and dtend When always_broadcast is False, these are the starting and ending dates when the campaign will be active.

rrule and rrule_text When always_broadcast is False, more complicated rules can be assigned to a campaign to determine when it can be triggered. For example, every Friday.

message The text of the campaign sent to end users of a Meridian-powered app.

link A link to a page or placemark within the app. Links can also be created for web URLs.

type A campaign can be active or passive. An active campaign provides greater control over the distance when a campaign triggers based on its RSSI.

active True or False. Whether a campaign is enabled or disabled.

target_url For campaigns notifying a 3rd-party endpoint, the URL for that endpoint.

Locations /events Endpoint

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

    /api/locations/{location_id}/events?page_size=100

Events Field Reference

Here are descriptions of the Events API endpoint fields.

created and modified Timestamps for when an event was created and when it was last modified.

id The event's unique ID.

name The event name.

description The event description.

allday True or False. Is the event an all day event?

dtstart and dtend The starting and ending dates for the event.

placemark and placemark_name The placemark ID and placemark name associated with the event, if any.

image_url If the event has an image, it's here.

feed If the event was created by a feed, this is its URL.

Locations /feeds Endpoint

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

    /api/locations/{location_id}/feeds

You can get information on a specific feed using its ID:

    /api/locations/{location_id}/feeds/{feed id}

Feeds Field Reference

created and modified Timestamps for when a feed was created in the Meridian Editor and when it was last modified.

id The unique feed ID.

url The feed URL.

name The feed name.

kind Feeds can be used for pages, placemarks, and events.

This field can be used as a filter.

type Feed types can be Meridian or custom.

This field can be used as a filter.

format For Meridian feed types, format can be JSON or XML. For custom feeds, you can use iCal, RSS, JSON, XML, or HTML.

auth_type This field is null if HTTP Basic Authentication isn't used.

mapping When using a custom type, this maps feed fields to Meridian fields.

updated The date of the last feed import.

imported_entities_count The number of items in the feed on the last import.

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
  • /locations/{location_id}/pages
  • /locations/{location_id}/events

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. For example, placemark, page, or event IDs. The objects are returned in the order they were uploaded.