Developer Guide

Getting Started

2.0 Getting Started

To develop applications for Veriplace, you will need to:

Register with Veriplace.
Understand how your application is allowed to use location data.
Integrate with the Veriplace API.
Review the path to certification.

2.1 Registering with Veriplace

You must register with Veriplace before you can start developing against its APIs.

To register, follow these steps:

Register for a developer account on the Veriplace Developer Portal: http://developer.veriplace.com
As part of this process, you will need to provide an email address and agree to the Developer Terms of Service.
Sign in to the developer site to create and manage your applications.
Each developer application receives credentials for using the APIs. For more details, see section 2.3.1.2 OAuth Credentials.
Build your application.
Your application can use the Veriplace SDK to get started quickly.
Test your application using simulated and/or developer-enabled accounts.
Applications in development are not allowed to locate the majority of Veriplace users; however each developer is assigned several simulated user accounts that may be used for testing purposes. In addition, non-simulated accounts may be developer-enabled to test with real location.

Once you are confident your application performs the way you want it to, you can submit it to Veriplace for testing and review. For more details, see section 2.4 Certifying and Launching Your Application.

2.2 Using Location Data

The Veriplace Developer Terms of Service places the following restrictions on how location data you obtain using Veriplace may be used:

Developers may not resell, aggregate, or use the data for any purpose other than what was specifically agreed to during developer registration or by a subsequent agreement.
Developers may not retain or employ location data after its expiration date. The expiration date is specified in the Veriplace XML schema document. For more information, see 4.2.7 Expiration Dates.
There is no need for developers to store location data themselves. Every location returned by Veriplace includes an identifier that can be used to subsequently retrieve it using the Past Location API. For more information, see section 5.0 Using the Past Location API.

Developers wanting to store location data must:

Ensure that personally identifiable information data (PII data) are not associated with position data in a non-secure form. Typically, encrypting the position data is sufficient.
Delete location data within 24 hours of its expiration.

If you have any questions about use or misuse of location data, contact your Veriplace representative at WaveMarket.

Note: WaveMarket subscribes to the CTIA Best Practices and Guidelines for Location Based Services.

2.3 Understanding the Veriplace APIs

To understand the Veriplace APIs, it is essential to understand the OAuth protocol and how it secures Protected Resources

2.3.1 OAuth

For security and privacy reasons, Veriplace restricts developer access to user identity and user location. These are considered protected resources, and typically require permission from the user before they can be accessed.

The Veriplace Developer API uses the OAuth standard for its API requests, which provides a framework for obtaining permission to access such protected resources. OAuth supplements standard HTTP requests, allowing XML encodings of these resources to be returned if permission is granted. While the OAuth protocol may be novel for some developers, library implementations are available for most development environments.

Note: We assume you are familiar with HTTP and XML in your preferred development environment.

The OAuth interaction leverages HTTP redirection to shift the responsibilty for authorization away from 3rd party applications onto Veriplace. This model allows Veriplace to be the only site that must be trusted for privacy decisions (by users and Wireless Carriers) and relieves 3rd party applications of this burden . To minimize the usability impact of HTTP redirection, Veriplace possesses co-branding facilities to enforce consistency between your application and the Veriplace UI.

2.3.1.1 OAuth Request URLs

The OAuth specification defines three request URLs, which Veriplace implements as:

Request Token URL:
```
https://veriplace.com/api/requestToken
```

User Authorization URL:

http://veriplace.com/api/userAuthorization

Access Token URL:
```
https://veriplace.com/api/accessToken
```

With the exception of User Authorization redirection,Veriplace APIs require HTTPS.

Requests for Veriplace’s User Authorization URL uses one required and one optional parameter: uri and immediate. You can find more information on the parameters in section 2.3.1.5 OAuth for User Discovery Workflow.

2.3.1.2 OAuth Credentials

Before using the Veriplace APIs, you must obtain the following:

An OAuth consumer key used for signing requests
An OAuth consumer secret use for signing request
An application-specific OAuth Access Token used to obtain certain protected resources

Your application's credentials are readily available from within the Veriplace Developer Portal.

2.3.1.3 More Information

Developers unfamiliar with OAuth are encouraged to review the OAuth specification and read one of the online tutorials.

General information about OAuth can be found at http://oauth.net.
More specific information about the OAuth specification can be found at http://oauth.net/documentation/spec.
The complete OAuth Core 1.0 specification can be found at http://oauth.net/core/1.0/.

Developers can find resources related to using OAuth in several places:

OAuth code documentation http://oauth.net/code
OAuth code repository http://oauth.googlecode.com/svn/code/
Google Code http://code.google.com/p/oauth/

2.3.1.4 How OAuth Works

Veriplace employs OAuth using the following general workflow:

Your application gets a one-time Request Token, which will subsequently be used to retrieve an Access Token if the user grants permission.
Your application redirects the User Agent to Veriplace, where the user is asked to provide authorization. The user may answer affirmatively, negatively, or may have the ability to give some form of partial consent. Veriplace subsequently redirects the User Agent back to your application.
Your application retrieves an Access Token using the Request Token as a key. Access Tokens correspond to the user's authorization decisions and will only exist if the user provided authorization. If the user did not permit access, no Access Token may be retrieved, and the process ends here.
If an Access Token is retrieved, it is used to gain access to the user’s location or to some other protected resource.
If the Access Token is for a single use, the token is invalidated after use; otherwise the Access Token can be re-used and may be cached.

2.3.1.5 OAuth for User Discovery Workflow

The OAuth workflow for user discovery is illustrated below.

devguide_userDisc_oAuth

2.3.1.6 OAuth for Location Workflow

The OAuth workflow for location access is illustrated below.

devguide_location_oAuth

2.3.1.7 Getting a Request Token

The developer must obtain a single-use Request Token for the transaction, using the Request Token URL:

https://veriplace.com/api/requestToken

Requests must use HTTP POST and must be signed using the HMAC-SHA1signature method.

2.3.1.8 Redirecting User Agent for User Authorization

Your application may be required to get authorization from the user before accessing protected resources. Your application gets this authorization by delegating to Veriplace via a redirect to the authorization URL:

http://veriplace.com/api/userAuthorization

Veriplace prompts the user to approve the request, logging in if necessary, and redirects back to the application. Application branding materials are displayed throughout the interaction, as shown below, to make the process appear seamless.

devguide_userDiscovery

Users see the screen above during user discovery and the screen below when granting permission to share their location.

devguide_shareLocation

When redirecting to Veriplace, the User Authorization URL must encode several parameters, as follows:

The oauth_token parameter identifies the previously obtained Request Token, which will typically be a randomly generated alpha-numeric string, such as TJTGzFqyx1bTJEourb3V.
The oauth_callback parameter identifies where the response should be sent upon completion, and could be something like:
```
http://example.com/callback
```
The Veriplace-specific uri parameter identifies the resource for which authorization is requested. This parameter is required.
The Veriplace-specific immediate parameter allows the application to avoid any user interaction. If set to "true", Veriplace will always redirect immediately back to the callback. An Access Token will be immediately available if and only if authorization was previously given. This parameter is optional and defaults to "false".

2.3.1.9 Getting an Access Token

The developer must exchange the Request Token for an Access Token using the following URL:

https://veriplace.com/api/accessToken

Requests must use HTTP POST and must be signed using the HMAC-SHA1signature method.

2.3.1.10 Managing Tokens

You may cache Access Tokens, but are not required to do so. Veriplace user authorization requests are idempotent: if authorization has already been granted, the user authorization process will bypass user interaction and immediately redirect back to the callback URL. This property can be used in conjunction with the immediate parameter to query for existing authorization.

If you choose to cache Access Tokens, you must ensure that storage is secure. Be aware that some Access Tokens are single-use only, and that all Access Tokens may expire or be revoked.

2.3.2 Protected Resources

User identity and location are OAuth protected resources and are represented using URLs following the REST model. The URL for accessing location is shown below.

https://veriplace.com/api/1.1/users/<userId>/locations

Note: Terms that appear in brackets are variables, for example, <userId> above.

You are strongly encouraged to use HTTPS for all protected resource URL requests.

2.3.2.1 Protected Resource Encodings: XML and JSON

By default, Veriplace encodes protected resource responses in XML, which is documented using XML Schema. Refer to the Veriplace XML Schema.

Applications can also choose to use JSON encoding, by adding the HTTP header "Accept: application/json" to the protected resource request. In most cases, the structure of the JSON data is based on the XML schema, using a one-to-one mapping of XML elements (or attributes) to JSON properties.

The Developer Guide sections describing specific APIs will provide examples of both XML and JSON responses.

2.4 Certifying and Launching Your Application

Once you are confident your application performs the way you want it to, you must submit it to WaveMarket for certification.

There are four steps to certifying and launching your Veriplace-powered application:

Prepare your application for final review.

Ensure that you have provided a complete and accurate description of your application on the Veriplace Developer Portal as well as up-to-date logos and other branding material. Veriplace uses your application’s branding during user authorization to create a better user experience.
Notify WaveMarket that your application is ready for testing by clicking the Publish Application link within your Veriplace Developer Portal account.

Your application must pass our final tests to be certified. You cannot make changes to your application once it is being reviewed.
Enter into a commercial agreement with WaveMarket and agree to any additional Terms of Service.

If you have not done so yet, you will be contacted by WaveMarket to discuss final pricing terms and sign a Pricing Rider. Depending on the nature of your application, there may be additional Terms to agree to. In some cases, carriers may have to sign off on applications for them to be certified.
WaveMarket certifies your application and it becomes available to your public users.

2.5 Billing and Payments

Billing and payments are handled with a pre-paid, declining balance model. Sign in to your developer account on the Veriplace Developer Portal to enter credit card information and deposit funds into your account. You can manually refill your account balance at any time. Optionally, you may elect to have your credit card automatically recharged when your balance approaches zero, to avoid interuptions in service.

Each successful Get Location request you make for a user's location deducts a small amount from your balance, as described in the Veriplace Developer Terms of Service and any Pricing Riders agreed upon by you and WaveMarket. If your balance ever runs out, you will not be able to locate end users.

To get you started quickly and let you experiment with the API without having to worry about credit card charges, each developer is provided with a set of simulated test users that can be located free of charge.

Location Labs

Universal Location Service