openapi: 3.0.3
info:
  title: Wikivoyage MediaWiki Action Authentication Search API
  description: 'The MediaWiki Action API is the primary programmatic interface for Wikivoyage, exposed at https://en.wikivoyage.org/w/api.php. All operations dispatch via the ?action= query parameter. The API supports JSON, XML, and PHP serialization; JSON is the recommended format.


    Wikivoyage covers travel destinations worldwide and the Action API enables retrieval of travel destination articles, accommodation listings, sightseeing information, and practical travel advice. Supports both anonymous reads and authenticated writes via OAuth 2.0.


    Wikimedia Foundation API guidelines require a contactable User-Agent header, serial (not parallel) calls for bulk work, and the maxlag parameter for automated clients.'
  version: '1.47'
  x-generated-from: documentation
  x-source-url: https://www.mediawiki.org/wiki/API:Main_page
  x-last-validated: '2026-06-13'
  contact:
    name: Wikimedia Foundation
    url: https://www.mediawiki.org/wiki/API:Etiquette
  license:
    name: CC BY-SA 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://en.wikivoyage.org/w
  description: English Wikivoyage
- url: https://{lang}.wikivoyage.org/w
  description: Per-language Wikivoyage
  variables:
    lang:
      default: en
      description: Language code (en, de, fr, es, it, pt, ru, zh, ...)
tags:
- name: Search
  description: Title and full-text search across Wikivoyage travel articles
paths:
  /search/page:
    get:
      operationId: searchPages
      summary: Wikivoyage Core REST Full-Text Search Travel Articles
      description: Full-text search of Wikivoyage travel article titles and contents. Supports keyword queries across all destination guides, accommodation listings, sightseeing information, and practical travel advice.
      tags:
      - Search
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Search query for travel destinations or topics
        example: Paris restaurants
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Result count limit
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /search/title:
    get:
      operationId: searchTitles
      summary: Wikivoyage Core REST Autocomplete Destination Title Search
      description: Auto-complete search of Wikivoyage travel article titles by prefix match. Useful for building destination lookup interfaces and travel search apps.
      tags:
      - Search
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Destination title prefix for autocomplete
        example: Par
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Result count limit
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SearchResponse:
      type: object
      properties:
        pages:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
    SearchResult:
      type: object
      description: A search result travel article entry.
      properties:
        id:
          type: integer
        key:
          type: string
        title:
          type: string
        excerpt:
          type: string
          description: HTML snippet with search match highlights
        matched_title:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        thumbnail:
          type: object
          nullable: true
          properties:
            url:
              type: string
              format: uri
            width:
              type: integer
            height:
              type: integer
            mimetype:
              type: string
              example: image/jpeg
    Error:
      type: object
      properties:
        errorKey:
          type: string
        messageTranslations:
          type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token from meta.wikimedia.org
    CookieAuth:
      type: apiKey
      in: cookie
      name: wikivoyagewikiUserID
      description: Session cookie obtained via action=login or action=clientlogin