Developer Guide
Veriplace XML Schema
Veriplace XML Schema
The Veriplace XML schema with annotations is provided below. For schema differences in older APIs, which are still supported, see Previous API Versions.
The latest (non-annotated) version can always be obtained from http://veriplace.com/xml/1.2/veriplace.xsd.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:vp="http://veriplace.com/xml/1.2"
targetNamespace="http://veriplace.com/xml/1.2"
version="1.0.1">
<!-- Top-level elements -->
<xs:element name="getLocationResult" type="vp:AsyncLocationResultType">
<xs:annotation>
<xs:documentation> Result of an asynchronous Get Location API request. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="identifiedUsers">
<xs:annotation>
<xs:documentation> Result of APIs that return a list of users indexed by their identifying properties. </xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="identifiedUser" type="vp:IdentifiedUserType" maxOccurs="unbounded" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="invitationResult" type="vp:InvitationResultType">
<xs:annotation>
<xs:documentation> Result of an asynchronous Invitation API request. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="location" type="vp:LocationResultType">
<xs:annotation>
<xs:documentation> Result of APIs that return a single user location or position error. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="nonce" type="vp:NonceType">
<xs:annotation>
<xs:documentation> A unique identifier for a request in progress. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="token" type="vp:TokenType">
<xs:annotation>
<xs:documentation> Result of APIs that return a single OAuth access token. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="user" type="vp:UserType">
<xs:annotation>
<xs:documentation> Result of APIs that return a single user identifier. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="users">
<xs:annotation>
<xs:documentation> Result of APIs that return a list of user identifiers. </xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="user" type="vp:UserType" maxOccurs="unbounded" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<!-- Complex types -->
<xs:complexType name="APIErrorType">
<xs:annotation>
<xs:documentation> Description of an error result from an asynchronous API request. </xs:documentation>
<xs:documentation> The error code and message correspond to the HTTP status code and message that would have been returned if the request had been made synchronously. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="code" type="xs:integer">
<xs:annotation>
<xs:documentation> A status code whose meaning is defined by the API that generated it. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="message" type="xs:string" minOccurs="0">
<xs:annotation>
<xs:documentation> An optional human-readable message to clarify the meaning of the error. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="AsyncLocationResultType">
<xs:annotation>
<xs:documentation> Result of an asynchronous Get Location request. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="nonce" type="vp:NonceType">
<xs:annotation>
<xs:documentation> The unique identifier for the request. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="user" type="vp:UserType" minOccurs="0">
<xs:annotation>
<xs:documentation> The Veriplace user identifier for the user who was located. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="mobileNumber" type="xs:string">
<xs:annotation>
<xs:documentation> The user's mobile number. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="apiError" type="vp:APIErrorType" minOccurs="0">
<xs:annotation>
<xs:documentation> Error description, if the request was not valid. </xs:documentation>
<xs:documentation> This means that the request was rejected for reasons that did not depend on the locatability of the user. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="location" type="vp:LocationResultType" minOccurs="0">
<xs:annotation>
<xs:documentation> Location information, if the request was valid. </xs:documentation>
<xs:documentation> This may contain a position element for an actual location, or, if the user could not be located, a positionError element. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="IdentifiedUserType">
<xs:annotation>
<xs:documentation> A mapping between an identifying property (e.g. mobile number) and a Veriplace user identifier.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="user" type="vp:UserType">
<xs:annotation>
<xs:documentation> The Veriplace user identifier. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute name="key" type="xs:string">
<xs:annotation>
<xs:documentation> The value that was used to identify the user. </xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="keyType" type="vp:UserKeyType">
<xs:annotation>
<xs:documentation> The type of value that was used to identify the user. </xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="IntersectionType">
<xs:annotation>
<xs:documentation> Description of a street intersection. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="position" type="vp:PositionType">
<xs:annotation>
<xs:documentation> Street names, city, state, postal code, and longitude and latitude coordinates. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="InvitationResultType">
<xs:annotation>
<xs:documentation> Result of an Invitation API request. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="nonce" type="vp:NonceType" minOccurs="0">
<xs:annotation>
<xs:documentation> The unique identifier for the request. </xs:documentation>
<xs:documentation> This is omitted if the user was already opted in and did not need to be invited. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="mobileNumber" type="xs:string">
<xs:annotation>
<xs:documentation> The mobile number to which the invitation was sent. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="user" type="vp:UserType" minOccurs="0">
<xs:annotation>
<xs:documentation> The Veriplace user identifier for that mobile number, if any. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="apiError" type="vp:APIErrorType" minOccurs="0">
<xs:annotation>
<xs:documentation> Error description, if the request failed. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="token" type="vp:TokenType" minOccurs="0">
<xs:annotation>
<xs:documentation> Permission token for the user, if the request succeeded. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="LocationResultType">
<xs:annotation>
<xs:documentation> The result of a user location query. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="created" type="xs:dateTime">
<xs:annotation>
<xs:documentation> The date and time at which this location was generated. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="expires" type="xs:dateTime">
<xs:annotation>
<xs:documentation> The date and time after which this location must be discarded. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:choice>
<xs:element name="position" type="vp:PositionType">
<xs:annotation>
<xs:documentation> Details of the location and optional address data. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="positionError" type="vp:PositionErrorType">
<xs:annotation>
<xs:documentation> Error description if a position was not available. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:choice>
<xs:element name="nearPointOfInterest" type="vp:POIReferenceType" minOccurs="0">
<xs:annotation>
<xs:documentation> Optional description of a geographic point of interest near this location. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="nearIntersection" type="vp:POIReferenceType" minOccurs="0">
<xs:annotation>
<xs:documentation> Optional description of a street intersection near this location. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute name="id" type="xs:unsignedLong">
<xs:annotation>
<xs:documentation> A unique identifier for this location result. </xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="NonceType">
<xs:annotation>
<xs:documentation> A unique identifier for a request in progress. </xs:documentation>
</xs:annotation>
<xs:attribute name="value" type="xs:string">
<xs:annotation>
<xs:documentation> The unique key. </xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="POIReferenceType">
<xs:annotation>
<xs:documentation> A geographic relation to a street intersection or other point of interest. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:choice>
<xs:element name="intersection" type="vp:IntersectionType">
<xs:annotation>
<xs:documentation> Position and description of an intersection. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="pointOfInterest" type="vp:POIType">
<xs:annotation>
<xs:documentation> Position and description of a point of interest. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:choice>
<xs:element name="distance" type="xs:double">
<xs:annotation>
<xs:documentation> Distance to the position, in meters. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="heading" type="xs:double">
<xs:annotation>
<xs:documentation> Heading to the position, in degrees clockwise from due north. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="POIType">
<xs:annotation>
<xs:documentation> Description of a geographic point of interest. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="name" type="xs:string">
<xs:annotation>
<xs:documentation> A descriptive name for the point of interest. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="category" type="xs:string">
<xs:annotation>
<xs:documentation> A general category for the point of interest. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="position" type="vp:PositionType">
<xs:annotation>
<xs:documentation> Position data and optional address data. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="phone" type="xs:string">
<xs:annotation>
<xs:documentation> The telephone number listed for the point of interest, if any. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PositionType">
<xs:annotation>
<xs:documentation> Geographic coordinates and optional address information. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="longitude" type="xs:double">
<xs:annotation>
<xs:documentation> Longitude in degrees. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="latitude" type="xs:double">
<xs:annotation>
<xs:documentation> Latitude in degrees. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="uncertainty" type="xs:double" minOccurs="0">
<xs:annotation>
<xs:documentation> An uncertainty radius around the longitude and latitude, measured in meters. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="address" type="vp:AddressType" minOccurs="0">
<xs:annotation>
<xs:documentation> Street/neighborhood/city information, if available. May not be reliable if the uncertainty is high. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PositionErrorType">
<xs:annotation>
<xs:documentation> An error returned while determining user location. </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="code" type="vp:PositionErrorCodeType">
<xs:annotation>
<xs:documentation> An enumerated error code. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="message" type="xs:string">
<xs:annotation>
<xs:documentation> A context-specific error string. </xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="cachedPosition" type="vp:PositionType" minOccurs="0">
<xs:annotation>
<xs:documentation> The last known position of the user, if available. </xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="TokenType">
<xs:annotation>
<xs:documentation> An OAuth access token. </xs:documentation>
</xs:annotation>
<xs:attribute name="value" type="xs:string">
<xs:annotation>
<xs:documentation> The token value. </xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="secret" type="xs:string">
<xs:annotation>
<xs:documentation> The token secret. </xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:complexType name="UserType">
<xs:annotation>
<xs:documentation> A Veriplace user identifier. </xs:documentation>
</xs:annotation>
<xs:attribute name="id" type="xs:unsignedLong">
<xs:annotation>
<xs:documentation> The unique key for this user. </xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<!-- Enumerated types -->
<xs:simpleType name="PositionErrorCodeType">
<xs:annotation>
<xs:documentation> Enumeration of possible error codes returned for user location. </xs:documentation>
</xs:annotation>
<xs:restriction base="xs:integer">
<xs:enumeration value="0">
<xs:annotation>
<xs:documentation> OK </xs:documentation>
<xs:documentation> Position determination was successful. </xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="100">
<xs:annotation>
<xs:documentation> Position Failure </xs:documentation>
<xs:documentation> Position determination was not successful. </xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="110">
<xs:annotation>
<xs:documentation> Position Determination Temporarily Unavailable </xs:documentation>
<xs:documentation> Position determination was not successful and the underlying position determination technology appears to be temporarily unable to obtain usable data. </xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="200">
<xs:annotation>
<xs:documentation> Restricted </xs:documentation>
<xs:documentation> Position determination was not attempted for privacy reasons. </xs:documentation>
</xs:annotation>
</xs:enumeration>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="UserKeyType">
<xs:annotation>
<xs:documentation> Enumeration of the properties that can be used to identify a user. </xs:documentation>
<xs:documentation> These are used for the keyType attribute of an identifiedUser element. </xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:enumeration value="mobile">
<xs:annotation>
<xs:documentation> The key is a mobile number. </xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="email">
<xs:annotation>
<xs:documentation> The key is an email address. </xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="openid">
<xs:annotation>
<xs:documentation> The key is an OpenID identifier. </xs:documentation>
</xs:annotation>
</xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:schema>