Documentation » Getting Started


LocalSocial is a Proximity Service that enables developers to quickly and easily add proximity functionality to their applications and services. “Proximity Functionality” includes being able to detect when another device of interest comes within range or goes out of range, and rapidly retrieving and storing application-level information associated with one or more devices nearby. It works with a range of short-range wireless technologies, across multiple platforms.

LocalSocial also gives end users of applications a simple way to manage and control how they interact with proximity-enabled applications, and to control and share information about themselves when they come in to contact with other people and businesses. The goal with LocalSocial is to offer a universal proximity utility that can be used in many different application scenarios. One of the guiding principles is to keep the service simple for both developers and end users.

How LocalSocial Works

The core concept in LocalSocial is the ability to manage associations between addresses and application information. addresses are widely dispersed and accessible in various forms of consumer electronics devices, including in Bluetooth, NFC and WiFi radios in phones, laptops, tablets, cars and elsewhere. LocalSocial provides a universal service that manages a store of MAC addresses on behalf of an application and enables efficient storage and retrieval of application information associated with these addresses.

  1. A “cloud” based service, available over the Internet, and accessed via public APIs. This is referred to as LocalSocial or “the LocalSocial Service”.

  2. Client-side libraries, designed for different target mobile devices, enabling application developers to quickly add proximity support to their applications. The libraries call the APIs provided by the LocalSocial Cloud Service.

  3. A website ( used by both developers and end users of the service. Developers use the site to register with the service, define new applications, get the libraries and tutorials, and view application analytics. End users can manage their devices and apps, control their own visibility and privacy, and also view analytics and activity history.

From a technical perspective, LocalSocial is composed of the following elements:


Cloud Based LocalSocial Service and API

The LocalSocial Service lives in the Cloud and provides APIs via Web Services and Restful APIs. The APIs are used primarily to store and lookup information about devices of interest (typically near) to the application.

An application must have a set of valid keys in order to access the API, and these are provided when a new application is registered with LocalSocial. When a mobile application accesses the LocalSocial service, the keys are included in the API requests, enabling LocalSocial to both control and track access to the service, and provide detailed analytics to the application developer.

The LocalSocial REST API supports JSON today. XML support will be added at a later date.

The LocalSocial Libraries

LocalSocial provides client side libraries, that a developer uses when building their application for a given target device, like an Android phone or tablet, or a Java-enabled phone. The libraries are used to give the developer a high level set of APIs to manage proximity functionality, and to abstract some of the detailed authentication steps used to access the LocalSocial API.

Libraries are available today for Android 2.x, and for J2ME. Other platforms will be added in time. If you have a platform of interest, please contact us.

LocalSocial Website

The LocalSocial website, at is used by both developers and end users of LocalSocial.

  • Developers use the site to register themselves, get the libraries, and register and track their applications.

  • End users use the site to manage and control their LocalSocial settings, setup and manage their applications and devices, and control their privacy across the LocalSocial platform. They can also use it to find new applications and services of interest.

LocalSocial in more detail

Core Concepts


Everything in LocalSocial is about devices – physical electronic devices that have some sort of digital wireless connectivity embedded in them. Phones, laptops, beacons, headsets and even cars are all examples of Devices from a LocalSocial perspective. A device can be anything that has a unique address, and some form of wireless connectivity. In particular, LocalSocial is concerned with relatively short-range connectivity, such as Bluetooth, NFC, ZigBee or WiFi. The service is designed to be neutral to the specific connectivity type: what’s of core interest to LocalSocial is that a device can be found or discovered in some standard way wirelessly, and that it has a unique address, which can be stored and subsequently retrieved from the LocalSocial Service online.


LocalSocial is a proximity service. A rule of thumb for LocalSocial is that anything that might be “visible” using short-range wireless technologies could be said to be “in proximity”. NFC has a very short range (measured in inches), Bluetooth typically has a range of 20-30 feet, and WiFi is often 50-100 feet in range. Anything “visible” using these wireless technologies can be said to be “in proximity”. LocalSocial is designed to enable applications to be aware of other devices in proximity, and to make it easy for developers to build that awareness in to their apps, to trigger a social or commercial interaction, relevant to their user.

Developers, Applications and APIs

LocalSocial is designed to be used by developers who are creating applications that take advantage of proximity. So a core element of the service is to enable developers to register with the service, and create applications that can use the service. A developer might create several applications that use LocalSocial. Each application registered with LocalSocial will have unique keys (or tokens) created for it. When a mobile application accesses the LocalSocial service, the keys are included in the API requests, enabling LocalSocial to both control and track access to the service, and provide useful analytics to the developer.


In considering how LocalSocial might be used by developers, it is likely to be very common that an application will wish to associate one or more pieces of application data with devices running or “seen by” the application. A developer may wish to keep such application data completely private, or to share some of the information with other users of the application, or to make the information public – visible to anyone else using LocalSocial who wishes to look it up. LocalSocial provides the notion of Tags to make it easy for the application developer to create, manage and find application data (both their own and others). Tags provide a flexible and simple store for small pieces of application data, and enable potentially rich interaction between users of LocalSocial-enabled applications.

Scans and ScanLogs

Whenever a wireless device “looks” for other wireless devices nearby, LocalSocial calls it a “scan”. For example, with Bluetooth, whenever an application looks for other Bluetooth devices in range, using device discovery, LocalSocial records this action as a scan. Any devices discovered are stored on behalf of the application in LocalSocial, and the record of that specific scan (the list of devices found on a given “sweep”) is called a scan log. Other wireless technologies have equivalent concepts (when you turn on WiFi on your laptop, you see a certain number of beacons).

Peer to Peer

It’s often very useful in an application to be able to exchange information between two or more devices that are in proximity directly, without having to go through some core / central authority. Bluetooth and other wireless technologies facilitate this peer-to-peer connectivity, but don’t always make it easy to program the peer-to-peer behaviour. LocalSocial provides peer-to-peer support, which can take advantage of the underlying capability in Bluetooth, WiFi Direct and other short range wireless technologies.

Social Aggregation

LocalSocial makes it easy to associate application specific information with any of the devices discovered or otherwise known to LocalSocial. One special category of information supported in the service is Social Network information. That is, LocalSocial specifically provides a social aggregation facility, making it easy for developers to let their end-users associate social network information with their device(s). By handling some of the required authorisation and formatting tasks involved in doing this, LocalSocial simplifies application development for developers whose apps can benefit from social network connectivity.

LocalSocial: Use cases (or: what’s it for?)

What is LocalSocial for? Glad you asked! If you have a mobile application in mind that can benefit from proximity – that is – being able to react when it’s near to another device, person or business of interest, then LocalSocial may be able to save you time and effort in creating your application, deploying it on mobile platforms, and tracking how it behaves. Below are some brief examples of what LocalSocial can be used for. Also try out some of the demo apps to get a feel for LocalSocial in action here

Social Proximity

LocalSocial makes it easy for your users to link their social identities (Facebook, Twitter, LinkedIn or others) to their mobile devices, and to share those identities with other people nearby. Using LocalSocial in this way, your app can become a social “radar” for other people nearby who have registered with your app, and enable “casual social browsing” – see Twitter, Facebook or other social information of interest from people nearby. For an example of this in action – see Dowser.

Peer-to-Peer gaming

with Bluetooth, you can create real peer to peer networks. LocalSocial simplifies the creation of those networks between people in proximity, and simplifies sharing their activity with one or more networks online. For example, you could share game status in real time with Facebook (”John has challenged Mike to a duel!“, “Mike is kicking John’s butt – help him out”…and so on).

Loyalty and Offers Based on Your Preferences

LocalSocial makes it easy to detect if someone of interest, or someone who has previously registered with your Application, is nearby. Shops and businesses can use this to create smarter proximity marketing solutions, based on user’s actual preferences. Most proximity marketing solutions to date are “dumb” in that they know nothing about the end user (recipient of a message / offer). LocalSocial enables users to register, share their social identity, and express their preferences for offers, loyalty tracking and more. Businesses can make offers and create real time deals based on actual user preferences, as they come close to a shop or location of interest.

Analytics and tracking

LocalSocial provides analytics on all proximity activity. Many uses, including footfall analysis, busy/peak times for locations, and repeat visitor analysis. See the Analytics pages and Retail collection App for examples.

LocalSocial Libraries

LocalSocial provides client side libraries for various platforms. Developers link with the libraries when building a proximity-enabled application. The libraries provide rich abstractions to handle proximity and core LocalSocial functionality, as well as providing authorisation functionality.

The main functions provided by the LocalSocial Libraries are:

  1. Registration / Authorisation with the LocalSocial Service

  2. Proximity Services: find devices of interest nearby, or register for alerts when given devices go in or go out of range

  3. Social Services: handle social connections to multiple social networks, port to and retrieve information from those networks on behalf of an application


The LocalSocial website has two main uses:

  1. End users of applications that are “LocalSocial enabled” can manage their settings here, including their profile, login details, registered applications and networks. They can also see analytics detail for themselves and control their privacy settings. There is also an app gallery of demonstration or interesting applications provided to enable users to try out some proximity-enabled applications that use LocalSocial here.

  2. Developers manage their applications, settings and track application usage and analytics here. Documentation, tutorials and sample applications and code are provided to enable developers to learn how to best use LocalSocial in their applications.