journeyed-org Agents API

openapi: 3.2.0
info:
  title: Journeyed answers Agents API
  version: '1'
  summary: Read-only, static JSON answers to local questions, with a source and a checked date on every fact.
  description: Static GET endpoints; no key, no rate plan, no write operations. Every page has a markdown twin at .md; every question, place and hub page also has a JSON twin at .json. Rankings are computed by published code (see the methodology page); sponsored placements are a separate, labelled array and never move a rank or score. No review text or star ratings are published. Journeyed is a Cloute company.
servers:
- url: https://journeyed.org
tags:
- name: Agents
paths:
  /agents/hotels/{market}/anchors.json:
    get:
      operationId: getHotelsAnchorIndex
      summary: 'Start here for a request: anchors with aliases, needs, and the questions and…'
      description: Match the place in a request to an anchor (name or alias) and the need to a need id (by its words). Fetch a question jsonUrl with that need, or the anchor factsUrl to filter hotels on the need fact keys and distance.
      parameters:
      - name: market
        in: path
        required: true
        description: Market slug, from answers.json or llms.txt.
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: los-angeles
      responses:
        '200':
          description: 'Start here for a request: anchors with aliases, needs, and the questions and facts file of each anchor'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnchorIndex'
        '404':
          description: 'No such page. Twins are not redirected: when a page moved or a question fell below the publish threshold, its HTML URL redirects but its .json and .md twins return 404, so re-read answers.json.'
      tags:
      - Agents
  /agents/hotels/{market}/facts/{anchor}.json:
    get:
      operationId: getHotelsAnchorFacts
      summary: Every scored hotel within one anchor radius with every verified fact
      description: 'Nearest first, with distance, score, phone, website and facts (value, source, checked date). Filter on distanceMi and on fact keys, reading each fact value: a fact can be a verified no.'
      parameters:
      - name: market
        in: path
        required: true
        description: Market slug, from answers.json or llms.txt.
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: los-angeles
      - name: anchor
        in: path
        required: true
        description: Anchor slug, from anchors.json.
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: alhambra
      responses:
        '200':
          description: Every scored hotel within one anchor radius with every verified fact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnchorFacts'
        '404':
          description: 'No such page. Twins are not redirected: when a page moved or a question fell below the publish threshold, its HTML URL redirects but its .json and .md twins return 404, so re-read answers.json.'
      tags:
      - Agents
  /agents/hotels/{market}/facts.json:
    get:
      operationId: getHotelsFactIndex
      summary: The fact dictionary and every verified fact in a market
      description: keys lists every fact key with its meaning, kind, unit and allowed values. hotels lists every hotel with a verified fact beyond contact details, one per line, each fact with its source and checked date. A key missing from a hotel is unknown, not absent.
      parameters:
      - name: market
        in: path
        required: true
        description: Market slug, from answers.json or llms.txt.
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: los-angeles
      responses:
        '200':
          description: The fact dictionary and every verified fact in a market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactIndex'
        '404':
          description: 'No such page. Twins are not redirected: when a page moved or a question fell below the publish threshold, its HTML URL redirects but its .json and .md twins return 404, so re-read answers.json.'
      tags:
      - Agents
  /agents/hotels/{market}/places.json:
    get:
      operationId: getHotelsPlaceDirectory
      summary: Every place in a market, one per line
      description: Contact, coordinates, score, verified fact keys and nearby anchors. Large; prefer anchors.json and an anchor facts file for a request.
      parameters:
      - name: market
        in: path
        required: true
        description: Market slug, from answers.json or llms.txt.
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: los-angeles
      responses:
        '200':
          description: Every place in a market, one per line
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceDirectory'
        '404':
          description: 'No such page. Twins are not redirected: when a page moved or a question fell below the publish threshold, its HTML URL redirects but its .json and .md twins return 404, so re-read answers.json.'
      tags:
      - Agents
components:
  schemas:
    AnchorFactsHotel:
      type: object
      required:
      - placeId
      - name
      - url
      - jsonUrl
      - distanceMi
      - score
      - lat
      - lon
      - address
      - phone
      - website
      - facts
      additionalProperties: false
      properties:
        placeId:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        jsonUrl:
          type: string
          format: uri
        distanceMi:
          type: number
        score:
          type:
          - number
          - 'null'
        lat:
          type: number
        lon:
          type: number
        address:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        website:
          type:
          - string
          - 'null'
          format: uri
        facts:
          type: array
          items:
            $ref: '#/components/schemas/CompactFact'
    DirectoryPlace:
      type: object
      description: 'One hotel of the place directory. formerNames (present only for a renamed hotel) lists the names it carried before: also known as.'
      required:
      - placeId
      - name
      - url
      - jsonUrl
      - lat
      - lon
      - address
      - phone
      - website
      - score
      - factKeys
      - nearAnchors
      - qaCount
      additionalProperties: false
      properties:
        placeId:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        jsonUrl:
          type: string
          format: uri
        lat:
          type: number
        lon:
          type: number
        address:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        website:
          type:
          - string
          - 'null'
          format: uri
        score:
          type:
          - number
          - 'null'
        factKeys:
          type: array
          items:
            type: string
        nearAnchors:
          type: array
          items:
            type: object
            required:
            - slug
            - distanceMi
            additionalProperties: false
            properties:
              slug:
                type: string
              distanceMi:
                type: number
        qaCount:
          type: integer
        formerNames:
          type: array
          items:
            type: string
    FactIndex:
      type: object
      description: 'The fact dictionary and compact fact index of one market (/agents/<category>/<market>/facts.json): every fact key that can exist, and every hotel with at least one verified fact, one per line. A key missing from a hotel is unknown, not absent.'
      required:
      - schemaVersion
      - type
      - jsonUrl
      - asOf
      - publisher
      - market
      - description
      - placesUrl
      - anchorsUrl
      - valueKinds
      - groups
      - keys
      - hotelsInMarket
      - count
      - hotels
      additionalProperties: false
      properties:
        schemaVersion:
          type: integer
          const: 1
        type:
          const: fact-index
        jsonUrl:
          type: string
          format: uri
        asOf:
          type: string
          format: date
        publisher:
          $ref: '#/components/schemas/Publisher'
        market:
          type: string
        description:
          type: string
        placesUrl:
          type: string
          format: uri
        anchorsUrl:
          type: string
          format: uri
        valueKinds:
          type: object
          additionalProperties:
            type: string
        groups:
          type: array
          items:
            type: object
            required:
            - id
            - label
            additionalProperties: false
            properties:
              id:
                type: string
              label:
                type: string
        keys:
          type: array
          items:
            $ref: '#/components/schemas/FactIndexKey'
        hotelsInMarket:
          type: integer
        count:
          type: integer
        hotels:
          type: array
          items:
            $ref: '#/components/schemas/FactIndexHotel'
    CompactFact:
      type: object
      description: A verified fact. source is the page URL it was read from, or the dataset id. License basis and source label are in the place JSON twin.
      required:
      - key
      - text
      - value
      - unit
      - source
      - checkedOn
      additionalProperties: false
      properties:
        key:
          type: string
        text:
          type: string
        value:
          type:
          - string
          - 'null'
        unit:
          type:
          - string
          - 'null'
        source:
          type: string
        checkedOn:
          type: string
          format: date
    PlaceDirectory:
      type: object
      description: 'Every active place in one market (/agents/<category>/<market>/places.json), one per line, with the fact keys verified for it and the anchors within 3 miles. Large: for lookups by name or for code.'
      required:
      - schemaVersion
      - type
      - jsonUrl
      - asOf
      - publisher
      - market
      - description
      - contactSource
      - count
      - places
      additionalProperties: false
      properties:
        schemaVersion:
          type: integer
          const: 1
        type:
          const: place-directory
        jsonUrl:
          type: string
          format: uri
        asOf:
          type: string
          format: date
        publisher:
          $ref: '#/components/schemas/Publisher'
        market:
          type: string
        description:
          type: string
        contactSource:
          oneOf:
          - $ref: '#/components/schemas/Source'
          - type: 'null'
        count:
          type: integer
        places:
          type: array
          items:
            $ref: '#/components/schemas/DirectoryPlace'
    Source:
      type: object
      required:
      - label
      - url
      - dataset
      - licenseBasis
      - checkedOn
      additionalProperties: false
      properties:
        label:
          type: string
        url:
          type:
          - string
          - 'null'
          format: uri
        dataset:
          type:
          - string
          - 'null'
        licenseBasis:
          type: string
        checkedOn:
          type: string
          format: date
    FactIndexKey:
      type: object
      description: 'One fact key of the dictionary: meaning, group, value kind, unit, allowed values (closed vocabularies) and how many hotels of the market have it verified.'
      required:
      - key
      - label
      - group
      - kind
      - unit
      - values
      - hotels
      additionalProperties: false
      properties:
        key:
          type: string
        label:
          type: string
        group:
          type: string
        kind:
          type: string
        unit:
          type:
          - string
          - 'null'
        values:
          oneOf:
          - type: array
            items:
              type: object
              required:
              - value
              - label
              additionalProperties: false
              properties:
                value:
                  type: string
                label:
                  type: string
          - type: 'null'
        hotels:
          type: integer
    Need:
      type: object
      description: 'A traveler need: words people use for it (hints, not exhaustive) and the fact keys that answer it. Empty factKeys: distance alone answers it.'
      required:
      - id
      - label
      - words
      - factKeys
      additionalProperties: false
      properties:
        id:
          type: string
        label:
          type: string
        words:
          type: array
          items:
            type: string
        factKeys:
          type: array
          items:
            type: string
    AnchorFacts:
      type: object
      description: 'Every scored hotel within an anchor radius, nearest first, with contact and every verified fact (/agents/<category>/<market>/facts/<anchor>.json). No ranking: filter it, reading each fact text or value (a fact can be a verified no, such as "No pets"). A missing fact is unverified, not false. One hotel per line.'
      required:
      - schemaVersion
      - type
      - jsonUrl
      - asOf
      - publisher
      - market
      - description
      - anchor
      - contactSource
      - count
      - factCounts
      - hotels
      additionalProperties: false
      properties:
        schemaVersion:
          type: integer
          const: 1
        type:
          const: anchor-facts
        jsonUrl:
          type: string
          format: uri
        asOf:
          type: string
          format: date
        publisher:
          $ref: '#/components/schemas/Publisher'
        market:
          type: string
        description:
          type: string
        anchor:
          type: object
          required:
          - slug
          - name
          - url
          - jsonUrl
          - lat
          - lon
          - radiusMi
          additionalProperties: false
          properties:
            slug:
              type: string
            name:
              type: string
            url:
              type: string
              format: uri
            jsonUrl:
              type: string
              format: uri
            lat:
              type: number
            lon:
              type: number
            radiusMi:
              type: number
        contactSource:
          oneOf:
          - $ref: '#/components/schemas/Source'
          - type: 'null'
        count:
          type: integer
        factCounts:
          type: object
          additionalProperties:
            type: integer
          description: Fact key -> how many hotels in this file have it verified, as a yes or a no.
        hotels:
          type: array
          items:
            $ref: '#/components/schemas/AnchorFactsHotel'
    Publisher:
      type: object
      description: The publisher. disclosure and parent are present only when the publisher has a parent company.
      required:
      - name
      additionalProperties: false
      properties:
        name:
          type: string
        disclosure:
          type: string
        parent:
          type: string
    AnchorIndexEntry:
      type: object
      description: 'One anchor (airport, venue, campus, neighborhood): its other names, its hub, its facts file and the published questions about it, each tagged with a need id.'
      required:
      - slug
      - name
      - kind
      - aliases
      - lat
      - lon
      - hubRadiusMi
      - radiusMi
      - hotelsInRadius
      - url
      - jsonUrl
      - markdownUrl
      - factsUrl
      - questions
      additionalProperties: false
      properties:
        slug:
          type: string
        name:
          type: string
        kind:
          type: string
        aliases:
          type: array
          items:
            type: string
        lat:
          type: number
        lon:
          type: number
        hubRadiusMi:
          type: number
        radiusMi:
          type: number
          description: 'Radius of factsUrl: the hub radius or the widest radius of a published question about this anchor, whichever is larger.'
        hotelsInRadius:
          type: integer
        url:
          type: string
          format: uri
        jsonUrl:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
        factsUrl:
          type: string
          format: uri
        questions:
          type: array
          items:
            $ref: '#/components/schemas/AnchorQuestion'
    FactIndexHotel:
      type: object
      description: 'One hotel of the fact index: every verified fact beyond contact details as its stored value, tied to the source and date it came from.'
      required:
      - placeId
      - name
      - url
      - jsonUrl
      - sources
      - facts
      additionalProperties: false
      properties:
        placeId:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        jsonUrl:
          type: string
          format: uri
        sources:
          type: array
          items:
            type: array
            prefixItems:
            - type: string
            - type: string
              format: date
            items:
              type: string
            minItems: 2
            maxItems: 2
            description: '[page URL or dataset id, checked date]'
        facts:
          type: object
          additionalProperties:
            type: array
            prefixItems:
            - type: string
            - type: integer
            items:
              type:
              - string
              - integer
            minItems: 2
            maxItems: 2
          description: fact key -> [stored value, index into sources]
    AnchorQuestion:
      type: object
      required:
      - need
      - question
      - url
      - jsonUrl
      - markdownUrl
      additionalProperties: false
      properties:
        need:
          type: string
        question:
          type: string
        url:
          type: string
          format: uri
        jsonUrl:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
    AnchorIndex:
      type: object
      description: 'Routing index of one market (/agents/<category>/<market>/anchors.json): map a request to an anchor (name or alias) and a need, then to a question or to the anchor facts file.'
      required:
      - schemaVersion
      - type
      - jsonUrl
      - asOf
      - publisher
      - market
      - description
      - marketHubUrl
      - placesUrl
      - factIndexUrl
      - answersUrl
      - steps
      - needs
      - anchors
      - marketQuestions
      additionalProperties: false
      properties:
        schemaVersion:
          type: integer
          const: 1
        type:
          const: anchor-index
        jsonUrl:
          type: string
          format: uri
        asOf:
          type: string
          format: date
        publisher:
          $ref: '#/components/schemas/Publisher'
        market:
          type: string
        description:
          type: string
        marketHubUrl:
          type: string
          format: uri
        placesUrl:
          type: string
          format: uri
        factIndexUrl:
          type: string
          format: uri
        answersUrl:
          type: string
          format: uri
        steps:
          type: array
          items:
            type: string
        needs:
          type: array
          items:
            $ref: '#/components/schemas/Need'
        anchors:
          type: array
          items:
            $ref: '#/components/schemas/AnchorIndexEntry'
        marketQuestions:
          type: array
          items:
            $ref: '#/components/schemas/AnchorQuestion'
x-mcp:
  url: https://journeyed.org/mcp
  transport: streamable-http
  authentication: none
  discovery: https://journeyed.org/.well-known/mcp.json