Creating a Value Function

A value function defines how contract pricing or value is calculated in the Optimize Everything API system. Value functions are composed of one or more standard functions, each with its own parameters.

Getting Started

Before diving into the technical details, we recommend using our Value Function Builder to create your first value function interactively.

Endpoint

POST /value-function/create

Required Fields

Name	Type	Required	Description	Default
name	string	Yes	Name of the value function	—
description	string	No	Description of what this value function calculates	—
maxValue	integer	Yes	Maximum possible value this function can return	—
minValue	integer	Yes	Minimum possible value this function can return	—
standardFunctions	array	Yes	List of standard functions that compose this value function	—

Standard Function Object

Each item in standardFunctions must have:

standardFunctionType (string): Type of standard function (Linear, Quadratic, Gaussian, Exponential, Conditional)
parameters (array): List of parameters for this function

Parameter Object

Each parameter must have:

index (integer): Parameter index position in the function
parameterType (string): Type of parameter (CONSTANT, RESULT_PARAMETER, NESTED_FUNCTION)
constant (float, optional): Constant value for this parameter (only used when parameterType is CONSTANT)
resultParameter (string, optional): Name of the trip result column to use as this parameter (only used when parameterType is RESULT_PARAMETER)
nestedFunctionId (integer, optional): ID of the nested value function to use as this parameter (only used when parameterType is NESTED_FUNCTION)

Parameter Types

CONSTANT

Uses the constant field for a fixed value. The value must be between -10000 and 10000.

RESULT_PARAMETER

Uses the resultParameter field to reference a trip result column. The column name must be one of the allowed column names.

NESTED_FUNCTION

Uses the nestedFunctionId field to reference another value function. This allows for complex function composition where one function can use the output of another function as input.

Nested Function Constraints:

Maximum nesting depth: 10 levels
Circular dependencies are not allowed
Nested functions must exist and belong to the same user
Nested functions are evaluated with the same input data as the parent function

Available Result Parameters

The resultParameter field refers to the name of a column in the trip result or operator/rider trip result table. This column will be used as the parameter value when evaluating the value function for a trip.

Note: For non-CONDITIONAL functions, the first parameter (index 0) typically represents the input value for the function.

Important: Time and distance values are always rounded up.

CargoTripResult (rider/cargo trips):

result_id: Unique identifier for the trip result
distance_walked_in_100_meters: Distance walked by the rider (100-meter units, rounded up)
time_in_transit_vehicle_in_minutes: Time spent in a transit vehicle (minutes, rounded up)
time_in_passenger_vehicle_in_minutes: Time spent in a passenger vehicle (minutes, rounded up)
vehicle_summary: JSON summary of vehicles used
total_time_in_minutes: Total trip time (minutes, rounded up)
departure_time_in_minutes_before_lat: Departure time before LAT (Latest Arrival Time) in minutes, rounded up
arrival_time_in_minutes_before_lat: Arrival time before LAT (Latest Arrival Time) in minutes, rounded up
departure_time_in_minutes_after_edt: Departure time after EDT (Earliest Departure Time) in minutes, rounded up
minimum_operator_rating: Minimum operator rating
minimum_operator_review_count: Minimum operator review count

OperatorTripResult (operator trips):

result_id: Unique identifier for the trip result
google_maps_estimated_trip_duration_in_minutes: Google Maps estimated trip duration (minutes, rounded up)
google_maps_estimated_trip_end_time: Google Maps estimated trip end time (datetime)
google_maps_estimated_waiting_time_in_minutes: Google Maps estimated waiting time (minutes, rounded up)
driving_time_in_minutes: When a leg start event is recorded, the time the leg started is recorded. When a leg end event is recorded, the time the leg ended is recorded. This is the sum of the duration of all legs in the operator trip. (minutes, rounded up)
driving_distance_in_km: When a leg end event is recorded, the operator will report the distance driven. This is the sum of this value for all of the legs in the operator trip. (kilometers, rounded up)
google_maps_estimated_driving_distance_in_meter: When a leg is started, Google Maps is used to get the driving distance for the best route. This value is the sum of this value for all the legs in the operator trip. (meters, rounded up)
vehicle_id: Vehicle ID used for the trip
minimum_rider_rating: Minimum rider rating
minimum_rider_review_count: Minimum rider review count

Parameter Requirements by Function Type

LINEAR Function

Equation: $f(x) = mx + b$

Index 0: Input value $x$ (typically a result parameter)
Index 1: Slope coefficient $m$
Index 2: Intercept value $b$

QUADRATIC Function

Equation: $f(x) = ax^2 + bx + c$

Index 0: Input value $x$ (typically a result parameter)
Index 1: Coefficient $a$ ( $x^2$ term)
Index 2: Coefficient $b$ ( $x$ term)
Index 3: Constant $c$

GAUSSIAN Function

Equation: $f(x) = e^{-(x-\mu)^2/(2\sigma^2)}$

Index 0: Input value $x$ (typically a result parameter)
Index 1: Mean value $\mu$
Index 2: Standard deviation $\sigma$

EXPONENTIAL Function

Equation: $f(x) = cb^x$

Index 0: Input value $x$ (typically a result parameter)
Index 1: Base value $b$
Index 2: Coefficient multiplier $c$

CONDITIONAL Function

Equation: $f(x) = \begin{cases} v_1 & \text{if } a \circ b \\ v_2 & \text{otherwise} \end{cases}$

Index 0: First operand $a$
Index 1: Comparison operator $\circ$ (e.g., greater than, less than, equals, greater than or equal, less than or equal)
Index 2: Second operand $b$
Index 3: Value if condition is true $v_1$
Index 4: Value if condition is false $v_2$

Example Request

{
  "name": "Distance Linear Value Function",
  "description": "Calculates value based on distance using a linear function.",
  "maxValue": 1000,
  "minValue": 0,
  "standardFunctions": [
    {
      "standardFunctionType": "LINEAR",
      "parameters": [
        {"index": 0, "parameterType": "RESULT_PARAMETER", "constant": null, "isConstant": false, "resultParameter": "driving_distance_in_km", "nestedFunctionId": null},
        {"index": 1, "parameterType": "CONSTANT", "constant": 0.5, "isConstant": true, "resultParameter": null, "nestedFunctionId": null},
        {"index": 2, "parameterType": "CONSTANT", "constant": 0.0, "isConstant": true, "resultParameter": null, "nestedFunctionId": null}
      ]
    }
  ]
}

Example with Nested Function

{
  "name": "Complex Pricing with Nested Function",
  "description": "Distance-based pricing with time multiplier using nested function",
  "maxValue": 200,
  "minValue": 0,
  "standardFunctions": [
    {
      "standardFunctionType": "LINEAR",
      "parameters": [
        {"index": 0, "parameterType": "NESTED_FUNCTION", "constant": null, "isConstant": false, "resultParameter": null, "nestedFunctionId": 123},
        {"index": 1, "parameterType": "CONSTANT", "constant": 1.5, "isConstant": true, "resultParameter": null, "nestedFunctionId": null},
        {"index": 2, "parameterType": "CONSTANT", "constant": 10.0, "isConstant": true, "resultParameter": null, "nestedFunctionId": null}
      ]
    }
  ]
}

Security & Performance Features

Security Features

Input sanitization prevents code injection attacks
Rate limiting: Maximum 50 functions per user per hour
Memory usage monitoring: Maximum 100MB per code generation
Code generation timeout: Maximum 5 seconds per generation
Generated code length limit: Maximum 10,000 characters
Deep nesting validation with full recursion
Circular dependency detection with full recursion

Performance Features

Code generation caching for improved performance
Memory usage monitoring and limits
Generation time tracking and limits
Optimized mathematical operations with safety checks

Error Handling

400: Invalid input, validation errors, circular dependencies, nesting depth exceeded
404: Referenced nested function not found
408: Code generation timeout
429: Rate limit exceeded
503: Memory limit exceeded

Getting Started​

Endpoint​

Required Fields​

Standard Function Object​

Parameter Object​

Parameter Types​

CONSTANT​

RESULT_PARAMETER​

NESTED_FUNCTION​

Available Result Parameters​

CargoTripResult (rider/cargo trips):​

OperatorTripResult (operator trips):​

Parameter Requirements by Function Type​

LINEAR Function​

QUADRATIC Function​

GAUSSIAN Function​

EXPONENTIAL Function​

CONDITIONAL Function​

Example Request​

Example with Nested Function​

Security & Performance Features​

Security Features​

Performance Features​

Error Handling​