models.openapiv3.examples.beamup.beamup.yaml Maven / Gradle / Ivy
# this is an example of the Beamup API
# as a demonstration of an API spec in YAML
openapi: "3.0.0"
info:
title: BeamUp API
description: Move your app forward with the BeamUp API
version: "1.0.0"
servers:
- url: https://api.beamup.com/v1
paths:
/products:
get:
summary: Product Types
description: The Products endpoint returns information about the Beamup products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order.
parameters:
- name: latitude
in: query
description: Latitude component of location.
required: true
schema:
type: number
format: double
- name: longitude
in: query
description: Longitude component of location.
required: true
schema:
type: number
format: double
security:
- apikey: []
tags:
- Products
responses:
200:
description: An array of products
content:
application/json:
schema:
$ref: "#/components/schemas/ProductList"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/estimates/price:
get:
summary: Price Estimates
description: The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.
The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.
parameters:
- name: start_latitude
in: query
description: Latitude component of start location.
required: true
schema:
type: number
format: double
- name: start_longitude
in: query
description: Longitude component of start location.
required: true
schema:
type: number
format: double
- name: end_latitude
in: query
description: Latitude component of end location.
required: true
schema:
type: number
format: double
- name: end_longitude
in: query
description: Longitude component of end location.
required: true
schema:
type: number
format: double
tags:
- Estimates
responses:
200:
description: An array of price estimates by product
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PriceEstimate"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/estimates/time:
get:
summary: Time Estimates
description: The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs.
parameters:
- name: start_latitude
in: query
description: Latitude component of start location.
required: true
schema:
type: number
format: double
- name: start_longitude
in: query
description: Longitude component of start location.
required: true
schema:
type: number
format: double
- name: customer_uuid
in: query
schema:
type: string
format: uuid
description: Unique customer identifier to be used for experience customization.
- name: product_id
in: query
schema:
type: string
description: Unique identifier representing a specific product for a given latitude & longitude.
tags:
- Estimates
responses:
200:
description: An array of products
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Product"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/me:
get:
summary: User Profile
description: The User Profile endpoint returns information about the Beamup user that has authorized with the application.
tags:
- User
responses:
200:
description: Profile information for a user
content:
application/json:
schema:
$ref: "#/components/schemas/Profile"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/history:
get:
summary: User Activity
description: The User Activity endpoint returns data about a user's lifetime activity with Beamup. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.
The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.
parameters:
- name: offset
in: query
schema:
type: integer
format: int32
description: Offset the list of returned results by this amount. Default is zero.
- name: limit
in: query
schema:
type: integer
format: int32
description: Number of items to retrieve. Default is 5, maximum is 100.
tags:
- User
responses:
200:
description: History information for the given user
content:
application/json:
schema:
$ref: "#/components/schemas/Activities"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
securitySchemes:
apikey:
type: apiKey
name: server_token
in: query
schemas:
Product:
type: object
properties:
product_id:
type: string
description: Unique identifier representing a specific product for a given latitude & longitude. For example, BeamupX in San Francisco will have a different product_id than BeamupX in Los Angeles.
description:
type: string
description: Description of product.
display_name:
type: string
description: Display name of product.
capacity:
type: integer
description: Capacity of product. For example, 4 people.
image:
type: string
description: Image URL representing the product.
ProductList:
type: object
properties:
products:
description: Contains the list of products
type: array
items:
$ref: "#/components/schemas/Product"
PriceEstimate:
type: object
properties:
product_id:
type: string
description: Unique identifier representing a specific product for a given latitude & longitude. For example, BeamupX in San Francisco will have a different product_id than BeamupX in Los Angeles
currency_code:
type: string
description: "[ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code."
display_name:
type: string
description: Display name of product.
estimate:
type: string
description: Formatted string of estimate in local currency of the start location. Estimate could be a range, a single number (flat rate) or "Metered" for TAXI.
low_estimate:
type: number
description: Lower bound of the estimated price.
high_estimate:
type: number
description: Upper bound of the estimated price.
surge_multiplier:
type: number
description: Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Price estimate already factors in the surge multiplier.
Profile:
type: object
properties:
first_name:
type: string
description: First name of the Beamup user.
last_name:
type: string
description: Last name of the Beamup user.
email:
type: string
description: Email address of the Beamup user
picture:
type: string
description: Image URL of the Beamup user.
promo_code:
type: string
description: Promo code of the Beamup user.
Activity:
type: object
properties:
uuid:
type: string
description: Unique identifier for the activity
Activities:
type: object
properties:
offset:
type: integer
format: int32
description: Position in pagination.
limit:
type: integer
format: int32
description: Number of items to retrieve (100 max).
count:
type: integer
format: int32
description: Total number of items available.
history:
type: array
items:
$ref: "#/components/schemas/Activity"
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string