timzinin-com Ispark Metro Destination Access Scorer API

openapi: 3.2.0
info:
  title: Zinin M2M Hub Ispark Metro Destination Access Scorer API
  description: Pay-per-call data & tool APIs
  version: 1.0.0
  x-guidance: 'Zinin M2M Hub — pay-per-call data & tool APIs for AI agents. Each POST /api/{slug} operation below is a distinct paid tool: call GET /api/{slug}/schema first for the exact input shape, then POST with a signed PAYMENT-SIGNATURE header (x402 v2, USDC — see x-payment-info per operation) or omit it to receive a 402 with full payment requirements in the PAYMENT-REQUIRED header. The same catalog is also available as MCP JSON-RPC tool bundles at POST /mcp/{bundle} — see GET /.well-known/x402 for the list of bundles.'
tags:
- name: Ispark Metro Destination Access Scorer
paths:
  /api/ispark-metro-destination-access-scorer:
    post:
      summary: İSPARK & Metro Destination Access Scorer
      description: Score customer sites against official Metro stations and İSPARK capacity. Unofficial, independent Actor; not affiliated with or endorsed by any named source publisher.
      operationId: call_ispark_metro_destination_access_scorer
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.020000'
        protocols:
        - x402: {}
        network: eip155:8453
        payTo: '0x409D32aD39C02BC9B23a8b2d447532ed801b12dE'
        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              schemaVersion: 1
              title: İSPARK & Metro Destination Access Scorer input
              description: Ranks customer-supplied Istanbul sites using straight-line proximity to official metro stations and İSPARK parking proximity/live capacity.
              type: object
              additionalProperties: false
              properties:
                requestId:
                  title: Request ID
                  description: Unique non-PII idempotency ID. Reusing it with different decision inputs fails.
                  type: string
                  pattern: ^[A-Za-z0-9_-]{8,64}$
                  minLength: 8
                  maxLength: 64
                  editor: textfield
                sites:
                  title: Candidate sites
                  description: One to 100 customer-owned site IDs and coordinates inside the bounded Istanbul service area.
                  type: array
                  minItems: 1
                  maxItems: 100
                  editor: json
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      siteId:
                        title: Site ID
                        description: Non-PII customer identity for this candidate site.
                        type: string
                        pattern: ^[A-Za-z0-9_-]+$
                        minLength: 1
                        maxLength: 64
                      latitude:
                        title: Latitude
                        description: WGS84 latitude inside the bounded Istanbul service area.
                        type: number
                        minimum: 40.7
                        maximum: 41.5
                      longitude:
                        title: Longitude
                        description: WGS84 longitude inside the bounded Istanbul service area.
                        type: number
                        minimum: 28.3
                        maximum: 30
                    required:
                    - siteId
                    - latitude
                    - longitude
                  default:
                  - siteId: kadikoy_candidate
                    latitude: 40.9909
                    longitude: 29.0221
                railWeight:
                  title: Metro weight
                  description: Share of the final score assigned to metro proximity. Parking receives one minus this value.
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 0.6
                  editor: number
                railReferenceMeters:
                  title: Metro reference distance (m)
                  description: Metro proximity reaches zero at and beyond this straight-line distance.
                  type: integer
                  minimum: 100
                  maximum: 5000
                  default: 1000
                  editor: number
                parkingReferenceMeters:
                  title: Parking reference distance (m)
                  description: Parking proximity reaches zero at and beyond this straight-line distance.
                  type: integer
                  minimum: 100
                  maximum: 5000
                  default: 750
                  editor: number
                minimumEmptySpaces:
                  title: Minimum empty spaces
                  description: Flags the nearest İSPARK facility when its reported live empty capacity is below this threshold.
                  type: integer
                  minimum: 0
                  maximum: 10000
                  default: 10
                  editor: number
                maxTotalChargeUsd:
                  title: Customer charge cap
                  description: Maximum accepted total run charge. A 100-site default-price batch needs at least $2.005 including Actor start.
                  type: number
                  minimum: 0.025
                  maximum: 100
                  default: 2.01
                  editor: number
              required:
              - requestId
              - sites
              - railWeight
              - railReferenceMeters
              - parkingReferenceMeters
              - minimumEmptySpaces
              - maxTotalChargeUsd
      responses:
        '200':
          description: Actor run succeeded and payment settled
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                    description: Actor output items — shape is actor-specific (varies per tool); see this operation's own requestBody schema/description for what the underlying actor produces.
                  meta:
                    type: object
                    properties:
                      run_ms:
                        type: integer
                        description: Actor run duration in milliseconds
                      item_count:
                        type: integer
                        description: len(results)
                      settled:
                        type: boolean
                        description: Whether the x402 payment was confirmed settled by the facilitator
                      transaction:
                        type:
                        - string
                        - 'null'
                        description: On-chain settlement transaction hash, null if unsettled
                    required:
                    - run_ms
                    - item_count
                    - settled
                    - transaction
                required:
                - results
                - meta
        '400':
          description: Malformed PAYMENT-SIGNATURE header or request body
        '402':
          description: Payment required or invalid — see PAYMENT-REQUIRED header
        '409':
          description: Payment payload already used
        '502':
          description: Actor run failed
        '504':
          description: Actor run timed out
      tags:
      - Ispark Metro Destination Access Scorer