Developer Guide
About Veriplace
1.0 About Veriplace
Veriplace is a comprehensive web platform that provides mobile users' location information to 3rd party applications using a standards-based developer API while empowering users to control when and how their locations can be accessed.
Veriplace is built to access location information from all Wireless Carriers and position determination technologies, including GPS, A-GPS, cell triangulation and cell tower solutions.
Veriplace supports all major mobile application platforms, including Web, WAP (mobile web), SMS, and native client (J2ME, BREW, Smart Phone).
1.1 Veriplace Architecture
From the perspective of an application developer, the Veriplace platform acts as an interchange between Wireless Carrier location data and 3rd party applications. Developer access to location is controlled by the API and by user-configured privacy rules.
The relationship between Veriplace, Wireless Carriers, 3rd party applications, and the Veriplace API is illustrated in the diagram below.
above: Veriplace architecture from a developer’s perspective
Veriplace sits between the wireless carrier network (on the left) and the developer of 3rd party applications (on the right). As a developer for Veriplace, you have direct access to the User Discovery API and the Get Location API and indirect access to the Privacy Engine and to Wireless Carriers.
- You use the User Discovery API to identify users. For more detailed information, see 3.0 Using the User Discovery API.
- You use the Get Location API to obtain user location information. For more detailed information, see 4.0 Using the Get Location API.
- The Privacy Engine manages user privacy decisions and controls location access using a fine-grained permission model.
- Veriplace manages all communications and integration with Wireless Carriers, which provide network-specific position determination technologies.
1.2 Wireless Carriers
Wireless Carriers employ a variety of network technologies to extract an individual user's location information. Since network architectures vary considerably among carriers, one of Veriplace's advantages is that it flexibly manages the requirements for communicating with different carrier technologies. Your application does not need to know or understand how location was obtained.
For example, many wireless devices today are equipped with GPS. In some cases, Wireless Carriers have deployed network-based solutions that allow access to GPS data from such devices; in other cases, similar solutions exist to access cell sector, cell tower, or cell triangulation data. It may also be possible to provision a mobile device with customized software that accesses location data and returns it to the Veriplace platform. Where these technologies have varying costs or limitations, Veriplace abstracts the notion of subscriber location so developers can focus on what's important and ignore the underlying position determination technology.
Most significantly, deriving the location of a mobile device can incur a cost at the underlying carrier. This cost is passed back to the Veriplace platform and onto the application developer. Veriplace supports a variety of pricing and business models to best support the requirements of the application developer.
1.3 Privacy Engine
Before allowing access to user location data, the Veriplace Privacy Engine authenticates and authorizes each 3rd party application request.
Individual users have authority over which applications can access their location. Veriplace provides users with a wide range of control over their permission preferences and also automates any carrier-specific logic related to permissioning decisions. For example, if your application wants to locate a mobile device that is being used by a minor, some carriers may require the authorization of and/or notification to the mobile account's owner, presumably the parent or custodian for the minor.
Veriplace takes responsibility for identifying and notifying the owner using whatever carrier system is available - your application doesn't have to anticipate this situation and others like it.
1.4 Platform Open Standards
Veriplace uses standards-based technologies, including HTTP, XML and OAuth (see below), which can be employed from any environment that developers prefer. Libraries for these technologies are available on every major development platform.
1.4.1 Advantages of Open Standards
Veriplace employs the OAuth standard in conjunction with XML over HTTP to provide greater power and easier integration when compared to existing location-based service standards, such as MLP and ParlayX. See 2.3.1 Using OAuth for more details. As a result, Veriplace gains the following advantages:
- Simplicity - existing standards are overly verbose and subject to many proprietary variations, which can make them difficult to use. Veriplace prefers a simpler and more effective approach, such as employing location modes instead of multiple parameters. See 4.2.6 Location Modes for more details.
- Ease of development - Veriplace adheres to the principles of REST, the open source architectural style advocating pragmatic practice with industry standards and eschewing complex request encodings in favor of well-defined HTTP URLs. This style permits more rapid development than existing location-based service standards, which often require hand-crafted XML or specialized libraries.
- Fine-grained privacy - existing standards support the rejection of location requests for privacy reasons (yes/no), but they provide no means for obtaining permission from users, nor do they expose nuanced privacy decisions at a finer grain than just yes/no.
- Feature richness - Veriplace APIs add user discovery, the ability to update location, and other functionality that follows from common application use cases.
1.4 Workflow
The general workflow for the majority of location requests is illustrated below.
There are two sections to the workflow – the top represents the User Discovery API, and the bottom the Location API. The former shows the User Discovery workflow with the user login method. This is described in more detail in 3.0 Using the User Discovery API. A modified version of the top section is shown below for User Discovery using Personal Identification Information (PII) – see 3.2.1 Applications Supply PII Data.
The column on the left describes the state needed by your application as you fetch token and location information. You can find more information on this flow in section 2.3.1.6 OAuth for Location Workflow. The column in the center describes the API events that occur as your application interacts with Veriplace. The column on the right shows how each API is involved during the workflow process.
1.6 API Overview
Veriplace developers have access to several different APIs. Most developers will only need to use two of these:
- User Discovery API lets developers discover user identities. See 3.0 Using the User Discovery API.
- Get Location API lets developers obtain individual user location information. See 4.0 Using the Get Location API.
Additionally, some developers may find the following APIs useful:
- Past Location API lets developers re-acquire individual user location information that was previously obtained. See 5.0 Using the Past Location API.
- Verify Permission API queries the server directly (rather than using interactive user authorization) for an existing permission to locate a user. See 6.0 Using the Verify Permission API.
- Permission Deletion API lets developers surrender permission to access individual user location information. See 7.0 Using the Permission Delete API.
1.7 Other Documentation
See the following documents for more information:
- Veriplace Developer Content Requirements for details about what types of applications and application behaviors are not allowed on the Veriplace platform.
- Veriplace SDK for details about downloading, installing and using the Veriplace SDK materials.