journeyed-org Hotel API

openapi: 3.2.0
info:
  title: Journeyed answers Hotel 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: Hotel
paths:
  /hotel/{place}.json:
    get:
      operationId: getHotel
      summary: One place with every sourced fact
      description: Contact details, coordinates, score and history, every fact with its source and checked date, counted mentions, distances to anchors and the questions it ranks for.
      parameters:
      - name: place
        in: path
        required: true
        description: Place slug, from a question or hub.
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: short-stories-hotel-los-angeles-00147d
      responses:
        '200':
          description: One place with every sourced fact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceTwin'
        '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:
      - Hotel
  /hotel/{place}.md:
    get:
      operationId: getHotelMarkdown
      summary: One place page as markdown
      parameters:
      - name: place
        in: path
        required: true
        description: Place slug, from a question or hub.
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: short-stories-hotel-los-angeles-00147d
      responses:
        '200':
          description: One place page as markdown
          content:
            text/markdown:
              schema:
                type: string
        '404':
          description: No such page.
      tags:
      - Hotel
components:
  schemas:
    Coordinates:
      type: object
      required:
      - lat
      - lon
      additionalProperties: false
      properties:
        lat:
          type: number
        lon:
          type: number
    RoutedDistance:
      type: object
      description: 'A distance along OpenStreetMap streets and paths between a hotel and a landmark, beside the straight-line distanceMi and never shorter than it. walkMin is the routing engine''s estimate (say "about"), never a measured time. driveMi is a distance only: no drive time is published. A null part is not on record.'
      required:
      - walkMi
      - walkMin
      - driveMi
      additionalProperties: false
      properties:
        walkMi:
          type:
          - number
          - 'null'
        walkMin:
          type:
          - integer
          - 'null'
        driveMi:
          type:
          - number
          - 'null'
    FactSheetRow:
      type: object
      description: 'One verified fact of a fact sheet: what the key means (label, group), its stored value and unit, the page wording, its source (exactly one of sourceUrl and dataset), the date it was checked and its data tier (1 open data, 2 the hotel website, 3 licensed, 4 first-party, 5 claimed by the business).'
      required:
      - key
      - label
      - group
      - value
      - unit
      - text
      - sourceUrl
      - dataset
      - checkedOn
      - tier
      - licenseBasis
      additionalProperties: false
      properties:
        key:
          type: string
        label:
          type: string
        group:
          type: string
        value:
          type:
          - string
          - 'null'
        unit:
          type:
          - string
          - 'null'
        text:
          type: string
        sourceUrl:
          type:
          - string
          - 'null'
          format: uri
        dataset:
          type:
          - string
          - 'null'
        checkedOn:
          type: string
          format: date
        tier:
          type: integer
          minimum: 1
          maximum: 5
        licenseBasis:
          type: string
    Routing:
      type: object
      description: 'What sources every routed figure of a twin: the credit (OpenStreetMap contributors, routed with the named engine), the date of the map data, the date computed and the method of each figure.'
      required:
      - source
      - engine
      - mapDataOn
      - computedOn
      - walkMethod
      - driveMethod
      - note
      additionalProperties: false
      properties:
        source:
          $ref: '#/components/schemas/Source'
        engine:
          type: string
        mapDataOn:
          type: string
          format: date
        computedOn:
          type: string
          format: date
        walkMethod:
          type: string
        driveMethod:
          type: string
        note:
          type: string
    Photo:
      type: object
      description: A licensed Wikimedia Commons photo the page shows. kind "place" is the hotel itself; "area" is a nearby landmark or city photo standing in for it (label says so); never treat an area photo as the hotel.
      required:
      - url
      - width
      - height
      - alt
      - kind
      - label
      - credit
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
        width:
          type: integer
        height:
          type: integer
        alt:
          type: string
        kind:
          enum:
          - place
          - area
          - landmark
        label:
          type:
          - string
          - 'null'
        credit:
          type: object
          required:
          - author
          - license
          - licenseUrl
          - commonsPage
          - fileTitle
          additionalProperties: false
          properties:
            author:
              type: string
            license:
              type: string
            licenseUrl:
              type: string
              format: uri
            commonsPage:
              type: string
              format: uri
            fileTitle:
              type: string
    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
    Fact:
      type: object
      description: One sourced fact. Exactly one of sourceUrl and dataset is set. text is the wording the page shows; value is the stored canonical value.
      required:
      - key
      - text
      - value
      - unit
      - sourceUrl
      - dataset
      - sourceLabel
      - licenseBasis
      - checkedOn
      additionalProperties: false
      properties:
        key:
          type: string
        text:
          type: string
        value:
          type:
          - string
          - 'null'
        unit:
          type:
          - string
          - 'null'
        sourceUrl:
          type:
          - string
          - 'null'
          format: uri
        dataset:
          type:
          - string
          - 'null'
        sourceLabel:
          type: string
        licenseBasis:
          type: string
        checkedOn:
          type: string
          format: date
    PlaceTwin:
      type: object
      description: JSON twin of a place page (<path>.json). photos is present when the build ships photos; videos when the place has YouTube videos; questionPages when the hotel has question pages.
      required:
      - schemaVersion
      - url
      - jsonUrl
      - markdownUrl
      - asOf
      - publisher
      - type
      - placeId
      - name
      - market
      - contact
      - coordinates
      - scoreName
      - score
      - scoreHistory
      - facts
      - factSheet
      - mentionCounts
      - anchors
      - routing
      - formerNames
      - nameSource
      - questions
      - sources
      - claimUrl
      - qa
      - brandStandard
      additionalProperties: false
      properties:
        schemaVersion:
          type: integer
          const: 1
        url:
          type: string
          format: uri
        jsonUrl:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
        asOf:
          type: string
          format: date
        publisher:
          $ref: '#/components/schemas/Publisher'
        type:
          const: place
        placeId:
          type: string
        name:
          type: string
        market:
          type: string
        contact:
          type: object
          description: Contact details from the open place record, plus ownerGuide when the owner publishes a guide site of their own (null when none is on record).
          required:
          - phone
          - website
          - address
          - source
          - ownerGuide
          additionalProperties: false
          properties:
            phone:
              type:
              - string
              - 'null'
            website:
              type:
              - string
              - 'null'
              format: uri
            address:
              type:
              - string
              - 'null'
            source:
              oneOf:
              - $ref: '#/components/schemas/Source'
              - type: 'null'
            ownerGuide:
              oneOf:
              - type: object
                description: A guide site the hotel owner publishes, apart from the brand site in website; the date a person checked it in a browser.
                required:
                - url
                - checkedOn
                additionalProperties: false
                properties:
                  url:
                    type: string
                    format: uri
                  checkedOn:
                    type: string
                    format: date
              - type: 'null'
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        scoreName:
          type: string
        score:
          oneOf:
          - type: object
            required:
            - value
            - formulaVersion
            - asOf
            additionalProperties: false
            properties:
              value:
                type: number
              formulaVersion:
                type: string
              asOf:
                type: string
                format: date
          - type: 'null'
        scoreHistory:
          type: array
          items:
            type: object
            required:
            - asOf
            - score
            additionalProperties: false
            properties:
              asOf:
                type: string
                format: date
              score:
                type: number
        facts:
          type: array
          items:
            $ref: '#/components/schemas/Fact'
        factSheet:
          $ref: '#/components/schemas/FactSheet'
        mentionCounts:
          type: array
          items:
            type: object
            description: Counted guest mentions from licensed sources. Never text, never a star rating.
            required:
            - aspect
            - positive
            - neutral
            - negative
            additionalProperties: false
            properties:
              aspect:
                type: string
              positive:
                type: integer
              neutral:
                type: integer
              negative:
                type: integer
        anchors:
          type: array
          items:
            type: object
            required:
            - name
            - url
            - distanceMi
            - routed
            additionalProperties: false
            properties:
              name:
                type: string
              url:
                type: string
                format: uri
              distanceMi:
                type: number
              routed:
                oneOf:
                - $ref: '#/components/schemas/RoutedDistance'
                - type: 'null'
        routing:
          oneOf:
          - $ref: '#/components/schemas/Routing'
          - type: 'null'
        formerNames:
          type: array
          items:
            type: string
        nameSource:
          oneOf:
          - $ref: '#/components/schemas/Source'
          - type: 'null'
        questions:
          type: array
          items:
            type: object
            required:
            - question
            - url
            - jsonUrl
            - rank
            additionalProperties: false
            properties:
              question:
                type: string
              url:
                type: string
                format: uri
              jsonUrl:
                type: string
                format: uri
              rank:
                type: integer
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
        claimUrl:
          type: string
          format: uri
        qa:
          type: array
          items:
            type: object
            description: A question about this hotel and its answer, restating one sourced fact (basis "fact:<key>") or one anchor distance (basis "distance:<anchor url>") on the page, with its source and checked date. Generated deterministically from the facts, never written by a model.
            required:
            - id
            - question
            - answer
            - source
            - basis
            additionalProperties: false
            properties:
              id:
                type: string
              question:
                type: string
              answer:
                type: string
              source:
                $ref: '#/components/schemas/Source'
              basis:
                type: array
                items:
                  type: string
        brandStandard:
          oneOf:
          - type: object
            description: What the hotel brand says all its hotels offer. Not a fact about this property.
            required:
            - brand
            - items
            additionalProperties: false
            properties:
              brand:
                type: string
              items:
                type: array
                items:
                  type: object
                  required:
                  - key
                  - text
                  - source
                  additionalProperties: false
                  properties:
                    key:
                      type: string
                    text:
                      type: string
                    source:
                      $ref: '#/components/schemas/Source'
          - type: 'null'
        questionPages:
          type: array
          items:
            type: object
            description: A page that answers one question about this hotel from its sourced facts (HotelQuestionTwin).
            required:
            - id
            - question
            - url
            - jsonUrl
            additionalProperties: false
            properties:
              id:
                type: string
              question:
                type: string
              url:
                type: string
                format: uri
              jsonUrl:
                type: string
                format: uri
        recognition:
          type: array
          items:
            $ref: '#/components/schemas/Fact'
        backing:
          $ref: '#/components/schemas/Backing'
        backedBy:
          type: string
        scoreBand:
          type: string
        bestOf:
          type: array
          items:
            type: object
            description: A best-of list this hotel is ranked on.
            required:
            - title
            - url
            - jsonUrl
            - rank
            additionalProperties: false
            properties:
              title:
                type: string
              url:
                type: string
                format: uri
              jsonUrl:
                type: string
                format: uri
              rank:
                type: integer
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
        videos:
          type: object
          description: 'J15: YouTube videos that name this hotel (title and channel as YouTube returns them, not verified). YouTube API data, refreshed or dropped within 30 days.'
          required:
          - source
          - note
          - terms
          - videos
          additionalProperties: false
          properties:
            source:
              const: YouTube Data API v3
            note:
              type: string
            terms:
              type: string
              format: uri
            videos:
              type: array
              items:
                type: object
                required:
                - videoId
                - title
                - channel
                - channelUrl
                - url
                - embedUrl
                - thumbnailUrl
                - kind
                - isShort
                - durationSec
                - uploadDate
                - fetchedOn
                additionalProperties: false
                properties:
                  videoId:
                    type: string
                  title:
                    type: string
                  channel:
                    type: string
                  channelUrl:
                    type: string
                    format: uri
                  url:
                    type: string
                    format: uri
                  embedUrl:
                    type: string
                    format: uri
                  thumbnailUrl:
                    type: string
                    format: uri
                  kind:
                    enum:
                    - room-tour
                    - walk-through
                    - review
                    - other
                  isShort:
                    type: boolean
                  durationSec:
                    type: integer
                  uploadDate:
                    type: string
                    format: date
                  fetchedOn:
                    type: string
                    format: date
    FactSheet:
      type: object
      description: 'The complete fact sheet of one hotel: every verified fact, and every registered fact key that is not verified yet (unknown). Unknown is not no: never fill it in. keysUrl is the market fact dictionary.'
      required:
      - about
      - keysUrl
      - known
      - unknownCount
      - facts
      - unknown
      - brandStandardKeys
      - routed
      additionalProperties: false
      properties:
        about:
          type: string
        keysUrl:
          type:
          - string
          - 'null'
          format: uri
        known:
          type: integer
        unknownCount:
          type: integer
        facts:
          type: array
          items:
            $ref: '#/components/schemas/FactSheetRow'
        unknown:
          type: array
          items:
            type: string
        brandStandardKeys:
          type: array
          items:
            type: string
        routed:
          type: array
          items:
            $ref: '#/components/schemas/FactSheetRoutedRow'
    FactSheetRoutedRow:
      type: object
      description: 'One computed distance of a fact sheet: straight-line miles to a landmark and the walking and driving distance along OpenStreetMap ways, with method, source and the date computed (checkedOn).'
      required:
      - anchor
      - url
      - straightMi
      - walkMi
      - walkMin
      - driveMi
      - method
      - sourceLabel
      - sourceUrl
      - licenseBasis
      - checkedOn
      additionalProperties: false
      properties:
        anchor:
          type: string
        url:
          type: string
          format: uri
        straightMi:
          type: number
        walkMi:
          type:
          - number
          - 'null'
        walkMin:
          type:
          - integer
          - 'null'
        driveMi:
          type:
          - number
          - 'null'
        method:
          type: string
        sourceLabel:
          type: string
        sourceUrl:
          type:
          - string
          - 'null'
          format: uri
        licenseBasis:
          type: string
        checkedOn:
          type: string
          format: date
    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
    Backing:
      type: object
      description: 'What is on record behind a hotel score, in counts: facts read from the hotel own website (and the newest date they were checked), contact details from the open place record, recognized awards, counted reader votes, and how many of the standard facts the score counts are verified.'
      required:
      - ownSiteFacts
      - ownSiteCheckedOn
      - recordFacts
      - awards
      - votes
      - standardFacts
      - standardTotal
      additionalProperties: false
      properties:
        ownSiteFacts:
          type: integer
        ownSiteCheckedOn:
          type:
          - string
          - 'null'
          format: date
        recordFacts:
          type: integer
        awards:
          type: integer
        votes:
          type: integer
        standardFacts:
          type: integer
        standardTotal:
          type: integer
x-mcp:
  url: https://journeyed.org/mcp
  transport: streamable-http
  authentication: none
  discovery: https://journeyed.org/.well-known/mcp.json