{
  "openapi": "3.1.0",
  "info": {
    "title": "Surroundings API",
    "version": "1.0.0",
    "description": "Read public example snapshots or run new address analyses with a Premium subscriber key."
  },
  "servers": [
    {
      "url": "https://www.surroundings.land"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/examples": {
      "get": {
        "operationId": "listExampleAnalyses",
        "summary": "List four public population analysis snapshots",
        "description": "Read-only, cached catalog. All bands are cumulative residential population estimates. Check dates, dataset version, limitations, and geographic boundaries before interpreting results.",
        "responses": {
          "200": {
            "description": "Curated examples",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/examples/{id}": {
      "get": {
        "operationId": "getExampleAnalysis",
        "summary": "Read a public example snapshot",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "toronto",
                "vancouver",
                "london",
                "melbourne",
                "singapore"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A saved example report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Example"
                }
              }
            }
          },
          "404": {
            "description": "Unknown example ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analyses": {
      "post": {
        "operationId": "createSubscriberAnalysis",
        "summary": "Analyze one address",
        "description": "Runs one analysis and saves the completed report. Use a distinct idempotency key per address. Identical retries replay the original result. Each completed address consumes one shared Premium query.",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriberAnalysisInput"
              },
              "example": {
                "address": "1311 S Keeler Ave, Chicago, IL 60623"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing completed result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriberAnalysis"
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                },
                "description": "Subscriber analysis status path."
              }
            }
          },
          "201": {
            "description": "New completed result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriberAnalysis"
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                },
                "description": "Subscriber analysis status path."
              }
            }
          },
          "202": {
            "description": "Analysis in progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriberPending"
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                },
                "description": "Subscriber analysis status path."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Subscriber key missing, invalid, expired or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Active Premium required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Saved report deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency key conflicts with another input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 8 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content type must be application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Another analysis is running or plan allowance exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "502": {
            "description": "Analysis failed. No query used.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary service failure or interrupted analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analyses/{id}": {
      "get": {
        "operationId": "getSubscriberAnalysis",
        "summary": "Retrieve your API-created analysis",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Completed analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriberAnalysis"
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                },
                "description": "Subscriber analysis status path."
              }
            }
          },
          "202": {
            "description": "Analysis in progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriberPending"
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                },
                "description": "Subscriber analysis status path."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "401": {
            "description": "Subscriber key missing, invalid, expired or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Active Premium required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Analysis unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Analysis could not complete because the plan allowance was exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Analysis failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary service failure or interrupted analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "operationId": "getSubscriberUsage",
        "summary": "Read your shared Premium query allowance",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription period usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriberUsage"
                }
              }
            }
          },
          "401": {
            "description": "Subscriber key missing, invalid, expired or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Active Premium required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary service failure or interrupted analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/batches": {
      "get": {
        "summary": "List the latest 20 owned batch summaries",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "batches": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BatchSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid subscriber key"
          },
          "403": {
            "description": "Premium required"
          },
          "404": {
            "description": "Not found or not owned"
          },
          "409": {
            "description": "Idempotency conflict, active batch, or cancelled batch"
          },
          "503": {
            "description": "Batch unavailable"
          }
        }
      },
      "post": {
        "summary": "Enqueue 2\u20131,000 addresses for a resumable background batch",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "links"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "links": {
                      "type": "object",
                      "required": [
                        "self",
                        "export"
                      ],
                      "properties": {
                        "self": {
                          "type": "string"
                        },
                        "export": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid subscriber key"
          },
          "403": {
            "description": "Premium required"
          },
          "404": {
            "description": "Not found or not owned"
          },
          "409": {
            "description": "Idempotency conflict, active batch, or cancelled batch"
          },
          "503": {
            "description": "Batch unavailable"
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{1,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "addresses"
                ],
                "additionalProperties": false,
                "properties": {
                  "addresses": {
                    "type": "array",
                    "minItems": 2,
                    "maxItems": 1000,
                    "items": {
                      "type": "string",
                      "minLength": 5,
                      "maxLength": 512
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/batches/{id}": {
      "get": {
        "summary": "Read batch summary and 50 item statuses, following next_cursor",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "summary",
                    "items",
                    "next_cursor"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "summary": {
                      "$ref": "#/components/schemas/BatchSummary"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BatchItem"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid subscriber key"
          },
          "403": {
            "description": "Premium required"
          },
          "404": {
            "description": "Not found or not owned"
          },
          "409": {
            "description": "Idempotency conflict, active batch, or cancelled batch"
          },
          "503": {
            "description": "Batch unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": -1,
              "maximum": 999,
              "default": -1
            }
          }
        ]
      },
      "patch": {
        "summary": "Pause, resume, cancel, or retry one failed item",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid subscriber key"
          },
          "403": {
            "description": "Premium required"
          },
          "404": {
            "description": "Not found or not owned"
          },
          "409": {
            "description": "Idempotency conflict, active batch, or cancelled batch"
          },
          "503": {
            "description": "Batch unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action"
                ],
                "additionalProperties": false,
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "pause",
                      "resume",
                      "cancel",
                      "retry"
                    ]
                  },
                  "item_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "address": {
                    "type": "string",
                    "minLength": 5,
                    "maxLength": 512
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/batches/{id}/export": {
      "get": {
        "summary": "Download owned batch CSV including unsuccessful rows",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "CSV export",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid subscriber key"
          },
          "403": {
            "description": "Premium required"
          },
          "404": {
            "description": "Not found or not owned"
          },
          "409": {
            "description": "Idempotency conflict, active batch, or cancelled batch"
          },
          "503": {
            "description": "Batch unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      }
    },
    "/api/v1/batches/{id}/items/{itemId}": {
      "get": {
        "summary": "Read one owned completed batch report without a query debit",
        "security": [
          {
            "SubscriberKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid subscriber key"
          },
          "403": {
            "description": "Premium required"
          },
          "404": {
            "description": "Not found or not owned"
          },
          "409": {
            "description": "Idempotency conflict, active batch, or cancelled batch"
          },
          "503": {
            "description": "Batch unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "PopulationBand": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "minutes",
          "population"
        ],
        "properties": {
          "minutes": {
            "type": "integer",
            "minimum": 1
          },
          "population": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "Example": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "api_version",
          "kind",
          "id",
          "location",
          "travel",
          "population",
          "limitations",
          "links"
        ],
        "properties": {
          "api_version": {
            "const": "1.0"
          },
          "kind": {
            "const": "example_analysis"
          },
          "id": {
            "type": "string",
            "enum": [
              "toronto",
              "vancouver",
              "london",
              "melbourne",
              "singapore"
            ]
          },
          "location": {
            "type": "object",
            "required": [
              "label",
              "city",
              "country",
              "address",
              "latitude",
              "longitude"
            ],
            "properties": {
              "label": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "address": {
                "type": "string"
              },
              "latitude": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "longitude": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              }
            }
          },
          "travel": {
            "type": "object",
            "required": [
              "mode",
              "minutes"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "driving",
                  "public_transport"
                ]
              },
              "transitTiming": {
                "const": "weekday_morning",
                "description": "Public transit examples use the weekday morning peak."
              },
              "minutes": {
                "type": "array",
                "items": {
                  "type": "integer"
                },
                "description": "Travel times in minutes, ordered from shortest to longest."
              }
            }
          },
          "population": {
            "type": "object",
            "required": [
              "unit",
              "basis",
              "cumulative",
              "bands",
              "source",
              "analyzed_on"
            ],
            "properties": {
              "unit": {
                "const": "people"
              },
              "basis": {
                "const": "modelled_residential"
              },
              "cumulative": {
                "const": true
              },
              "bands": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PopulationBand"
                },
                "description": "Each population includes every shorter travel-time band; do not add these cumulative totals together."
              },
              "source": {
                "type": "object",
                "required": [
                  "name",
                  "dataset_version",
                  "estimate_year"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "dataset_version": {
                    "type": "string"
                  },
                  "estimate_year": {
                    "type": "integer"
                  }
                }
              },
              "analyzed_on": {
                "type": "string",
                "format": "date",
                "description": "Date the saved report was generated, shown in the site operator\u2019s America/Vancouver timezone."
              }
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "links": {
            "type": "object",
            "required": [
              "report",
              "report_image",
              "pricing"
            ],
            "properties": {
              "report": {
                "type": "string",
                "format": "uri"
              },
              "report_image": {
                "type": "string",
                "format": "uri"
              },
              "pricing": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "Catalog": {
        "type": "object",
        "required": [
          "api_version",
          "mode",
          "can_run_custom_analyses",
          "data",
          "links"
        ],
        "properties": {
          "api_version": {
            "const": "1.0"
          },
          "mode": {
            "const": "public_examples"
          },
          "can_run_custom_analyses": {
            "const": false
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Example"
            }
          },
          "links": {
            "type": "object",
            "properties": {
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "guide": {
                "type": "string",
                "format": "uri"
              },
              "pricing": {
                "type": "string",
                "format": "uri"
              },
              "subscriber_access": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "const": "EXAMPLE_NOT_FOUND"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "SubscriberAnalysisInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "address": {
            "type": "string",
            "minLength": 5,
            "maxLength": 512
          },
          "acres": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100000,
            "description": "Optional parcel acreage. The workspace uses a one-acre placeholder when omitted."
          },
          "travel_options": {
            "type": "object",
            "deprecated": true,
            "description": "Accepted for compatibility. New analyses always use Mapbox driving at 15, 30, 45, and 60 minutes.",
            "additionalProperties": false,
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "driving",
                  "public_transport",
                  "walking",
                  "cycling",
                  "bus",
                  "coach",
                  "train",
                  "ferry",
                  "driving+ferry",
                  "cycling+ferry",
                  "driving+train",
                  "driving+public_transport",
                  "cycling+public_transport"
                ],
                "default": "driving"
              },
              "minutes": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 240
                },
                "minItems": 1,
                "maxItems": 10,
                "default": [
                  15,
                  30,
                  45,
                  60
                ]
              },
              "departureTime": {
                "type": "string",
                "format": "date-time"
              },
              "transitTiming": {
                "const": "weekday_morning"
              }
            },
            "required": []
          }
        },
        "required": [
          "address"
        ]
      },
      "SubscriberPending": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "const": "pending"
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "self": {
                "type": "string",
                "format": "uri-reference"
              }
            },
            "required": [
              "self"
            ]
          }
        },
        "required": [
          "id",
          "status",
          "links"
        ]
      },
      "SubscriberAnalysis": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "const": "completed"
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "self": {
                "type": "string",
                "format": "uri-reference"
              }
            },
            "required": [
              "self"
            ]
          },
          "report": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "address": {
                "type": "string"
              },
              "location": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "latitude": {
                    "type": "number"
                  },
                  "longitude": {
                    "type": "number"
                  },
                  "postal_code": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "country_code": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "latitude",
                  "longitude",
                  "postal_code",
                  "country_code"
                ]
              },
              "travel_options": {
                "anyOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "mode": {
                        "type": "string",
                        "enum": [
                          "driving",
                          "public_transport",
                          "walking",
                          "cycling",
                          "bus",
                          "coach",
                          "train",
                          "ferry",
                          "driving+ferry",
                          "cycling+ferry",
                          "driving+train",
                          "driving+public_transport",
                          "cycling+public_transport"
                        ],
                        "default": "driving"
                      },
                      "minutes": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 240
                        },
                        "minItems": 1,
                        "maxItems": 10,
                        "default": [
                          15,
                          30,
                          45,
                          60
                        ]
                      },
                      "departureTime": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "transitTiming": {
                        "const": "weekday_morning"
                      }
                    },
                    "required": []
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "population": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "unit": {
                    "const": "people"
                  },
                  "basis": {
                    "const": "modelled_residential"
                  },
                  "cumulative": {
                    "const": true
                  },
                  "source": {
                    "type": "string"
                  },
                  "bands": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "minutes": {
                          "type": "integer"
                        },
                        "population": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "minutes",
                        "population"
                      ]
                    }
                  }
                },
                "required": [
                  "unit",
                  "basis",
                  "cumulative",
                  "source",
                  "bands"
                ]
              },
              "housing_units": {
                "type": "object",
                "description": "Cumulative US estimates keyed by travel minutes, using ACS 2020\u20132024 table B25001. Null per band indicates unavailable coverage. The field may be omitted outside the US.",
                "additionalProperties": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 0
                }
              },
              "market_benchmark": {
                "anyOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "geography": {
                        "const": "us_zip_code"
                      },
                      "postal_code": {
                        "type": "string"
                      },
                      "reporting_month": {
                        "type": "string"
                      },
                      "currency": {
                        "const": "USD"
                      },
                      "average_list_price": {
                        "anyOf": [
                          {
                            "type": "number"
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "ZIP-level housing asking price for the reporting month. This is a geographic benchmark rather than the lot asking price."
                      },
                      "active_listings": {
                        "anyOf": [
                          {
                            "type": "integer"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "required": [
                      "geography",
                      "postal_code",
                      "reporting_month",
                      "currency",
                      "average_list_price",
                      "active_listings"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "analyzed_at": {
                "type": "string",
                "format": "date-time"
              },
              "population_2024": {
                "$ref": "#/components/schemas/SubscriberPopulation2024",
                "description": "Standalone cumulative WorldPop 2024 residential population estimate for each catchment."
              },
              "population_change": {
                "$ref": "#/components/schemas/SubscriberCatchmentChanges",
                "minItems": 4,
                "maxItems": 4,
                "description": "WorldPop residential population change in people from 2021 and 2016 to each of 2026 and 2024. Both estimates use the raster coverage shared by their endpoints."
              },
              "area_income": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/SubscriberAreaIncome"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "US cumulative modeled aggregate household income from ACS B19025, in 2024 USD."
              },
              "area_income_change": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/SubscriberCatchmentChanges",
                    "minItems": 2,
                    "maxItems": 2
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "US modeled area income change in constant 2024 USD from 2021 and 2016 to 2024. Each comparison uses shared raster coverage."
              },
              "housing_unit_change": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/SubscriberCatchmentChanges",
                    "minItems": 2,
                    "maxItems": 2
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "US modeled housing unit change from 2021 and 2016 to 2024. Each comparison uses shared raster coverage."
              },
              "house_price_change": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/SubscriberHousePriceChange"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "FHFA nominal cumulative single-family house price changes for the origin US ZIP, including 2021\u20132024 and 2016\u20132024 alongside the 1-, 5-, and 10-year comparisons."
              }
            },
            "required": [
              "address",
              "location",
              "travel_options",
              "population",
              "market_benchmark",
              "analyzed_at",
              "population_2024",
              "population_change",
              "area_income",
              "area_income_change",
              "housing_unit_change",
              "house_price_change"
            ]
          }
        },
        "required": [
          "id",
          "status",
          "links",
          "report"
        ]
      },
      "SubscriberUsage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "period_start": {
            "type": "string",
            "format": "date-time"
          },
          "period_end": {
            "type": "string",
            "format": "date-time"
          },
          "limit": {
            "type": "integer"
          },
          "used": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer"
          }
        },
        "required": [
          "period_start",
          "period_end",
          "limit",
          "used",
          "remaining"
        ]
      },
      "SubscriberPopulation2024": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "year": {
            "const": 2024
          },
          "unit": {
            "const": "people"
          },
          "basis": {
            "const": "modelled_residential"
          },
          "cumulative": {
            "const": true
          },
          "source": {
            "const": "worldpop-2024-r2025a-1km-ua-v1"
          },
          "bands": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "minutes": {
                  "type": "integer"
                },
                "population": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "minutes",
                "population"
              ]
            }
          }
        },
        "required": [
          "year",
          "unit",
          "basis",
          "cumulative",
          "source",
          "bands"
        ]
      },
      "SubscriberCatchmentChanges": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "start_year": {
              "type": "integer"
            },
            "end_year": {
              "type": "integer"
            },
            "bands": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "minutes": {
                    "type": "integer"
                  },
                  "start": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "end": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "change": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "percent_change": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                "required": [
                  "minutes",
                  "start",
                  "end",
                  "change",
                  "percent_change"
                ]
              }
            }
          },
          "required": [
            "start_year",
            "end_year",
            "bands"
          ]
        },
        "description": "Bands are cumulative. Null values indicate unavailable data or an undefined percentage."
      },
      "SubscriberAreaIncome": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "currency": {
            "const": "USD"
          },
          "basis": {
            "const": "modeled_aggregate_household_income"
          },
          "cumulative": {
            "const": true
          },
          "bands": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "minutes": {
                  "type": "integer"
                },
                "area_income": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "minutes",
                "area_income"
              ]
            }
          }
        },
        "required": [
          "currency",
          "basis",
          "cumulative",
          "bands"
        ]
      },
      "SubscriberHousePriceChange": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "geography": {
            "const": "us_zip_code"
          },
          "postal_code": {
            "type": "string"
          },
          "source": {
            "const": "fhfa_zip_house_price_index"
          },
          "release_date": {
            "type": "string",
            "format": "date"
          },
          "periods": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "start_year": {
                  "type": "integer"
                },
                "end_year": {
                  "type": "integer"
                },
                "percent_change": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "start_year",
                "end_year",
                "percent_change"
              ]
            },
            "minItems": 5,
            "maxItems": 5
          }
        },
        "required": [
          "geography",
          "postal_code",
          "source",
          "release_date",
          "periods"
        ]
      },
      "BatchSummary": {
        "type": "object",
        "required": [
          "id",
          "state",
          "createdAt",
          "counts",
          "targetConcurrency",
          "completionTargetSeconds"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "running",
              "paused",
              "completed",
              "cancelled"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "counts": {
            "type": "object",
            "required": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled"
            ],
            "properties": {
              "queued": {
                "type": "integer",
                "minimum": 0
              },
              "running": {
                "type": "integer",
                "minimum": 0
              },
              "completed": {
                "type": "integer",
                "minimum": 0
              },
              "failed": {
                "type": "integer",
                "minimum": 0
              },
              "cancelled": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "targetConcurrency": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "ceil(unique property count / 10), subject to shared capacity"
          },
          "completionTargetSeconds": {
            "type": "integer",
            "const": 300,
            "description": "Completion goal, not a guaranteed maximum; includes no promise about provider or infrastructure timing"
          }
        }
      },
      "BatchItem": {
        "type": "object",
        "required": [
          "id",
          "ordinal",
          "address",
          "state",
          "errorCode"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "ordinal": {
            "type": "integer",
            "minimum": 0
          },
          "address": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled"
            ]
          },
          "errorCode": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "SubscriberKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Create a revocable 90-day key at /account/api-access while signed in with Premium."
      }
    }
  }
}
