---
openapi: 3.0.1
info:
  title: Opendata YTJ-Api
  version: 2.0
  license:
    name: Creative Commons Nimeä 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers: 
  - url: https://avoindata.prh.fi/opendata-ytj-api/v3
paths:
  /companies:
    get:
      summary: "Search for companies by company name, place of registered office, Business ID or company form"
      operationId: GetCompanies
      parameters:
        - in: query
          name: name
          description: "Company name (search for current or previous company names, parallel company names or auxiliary company names)"
          schema:
            type: string
        - in: query
          name: location
          description: "Town or city"
          schema:
            type: string
        - in: query
          name: businessId
          description: "Business ID"
          schema:
            type: string
        - in: query
          name: companyForm
          description: >
            <a aria-label="Opens in a new window" rel="noopener" href="/opendata-ytj-api/v3/description?code=YRMU&lang=en">Company form <svg width="15" height="20" viewBox="0 -11 24 24"> <path margin="0" fill="#035ca7" d="M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708"></path></svg></a>
          schema:
            type: string
            enum: [ "AOY", "ASH", "ASY", "AY", "AYH", "ETS", "ETY", "SCE", "SCP", "HY", "KOY", "KVJ", "KVY", "KY", "OK",
                      "OP", "OY", "OYJ", "SE", "SL", "SP", "SÄÄ", "TYH", "VOJ", "VOY", "VY", "VALTLL"]
        - in: query
          name: mainBusinessLine
          description: >
            <a aria-label="Opens in a new window" rel="noopener" href="https://www.stat.fi/en/luokitukset/toimiala/">Main line of business <svg width="15" height="20" viewBox="0 -6 24 24"> <path margin="0" fill="#035ca7" d="M14,3V5H17.59L7.76,14.83L9.17,16.24L19,6.41V10H21V3M19,19H5V5H12V3H5C3.89,3 3,3.9 3,5V19A2,2 0 0,0 5,21H19A2,2 0 0,0 21,19V12H19V19Z"></path></svg></a>(Search by Statistics Finland TOL 2008 code or by text)
          schema:
            type: string
        - in: query
          name: registrationDateStart
          description: "Company registration date over a period of time (write the start date in the format yyyy-mm-dd)"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: registrationDateEnd
          description: "Company registration date over a period of time (write the end date in the format yyyy-mm-dd)"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: postCode
          description: "Postal code of street or postal address"
          schema:
            type: string
        - in: query
          name: businessIdRegistrationStart
          description: "Date of grant of Business ID over a period of time (Write the start date in the format yyyy-mm-dd)"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: businessIdRegistrationEnd
          description: "Date of grant of Business ID over a period of time (write the end date in the format yyyy-mm-dd)"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: page
          description: "If your search returns more than 100 results, they are shown on multiple pages. Use the page parameter to indicate the results page you need. If the page parameter is not used or it points to a page not included in the results, the results of the first page are returned (for instance if you search for page 5 and the results only have 3 pages)."
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResult'
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Too many requests"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "The server cannot process the request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /all_companies:
    get:
      summary: "Get all companies on the Finnish Trade Register, and pending companies, as a JSON file"
      operationId: GetAllCompanies
      responses:
        200:
          description: "OK"
          content:
            application/zip:
              schema:
                type: string
                format: binary
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Too many requests"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "The server cannot process the request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /description:
    get:
      summary: "Retrieve code list details"
      operationId: GetDescription
      parameters:
        - in: query
          name: code
          required: true
          description: "Code"
          schema:
            type: string
            enum: [ "YRMU", "REK_KDI", "TLAJI", "SELTILA", "REK", "VIRANOM", "TLAHDE", "KIELI", "TOIMI", "TOIMI2", "TOIMI3", "KONK", "SANE", "STATUS3", "SELTILA,SANE,KONK" ]
        - in: query
          name: lang
          required: true
          description: "Language code"
          schema:
            type: string
            enum: [ "en", "fi", "sv" ]
      responses:
        200:
          description: "OK"
          content:
            text/plain:
              schema:
                type: string
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Too many requests"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "The server cannot process the request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /post_codes:
    get:
      summary: "Retrieve postal code details"
      operationId: GetPostCodes
      parameters:
        - in: query
          name: lang
          required: true
          description: "Language code"
          schema:
            type: string
            enum: [ "en", "fi", "sv" ]
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostOfficeEntry'
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Too many requests"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "The server cannot process the request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CompanyResult:
      type: object
      description: "Details of company or organisation"
      required: ["totalResults", "companies"]
      properties:
        totalResults:
          type: integer
          format: int64
          description: "Total number of results"
        companies:
          type: array
          description: "Details of company or organisation"
          items:
            $ref: '#/components/schemas/Company'
    Company:
      type: object
      description: "Details of company or organisation"
      required: ["businessId", "registeredEntries", "tradeRegisterStatus", "lastModified"]
      properties:
        businessId:
          type: object
          required: ["value", "source"]
          description: "Business ID, for example 0116297-6"
          properties:
            value:
              type: string
              description: "Business ID"
              minLength: 9
              maxLength: 9
            registrationDate:
              type: string
              nullable: true
              format: date
              description: "Y-tunnuksen antamispäivä"
              minLength: 10
              maxLength: 10
            source:
              $ref: '#/components/schemas/Source'
        euId:
          type: object
          required: ["value", "source"]
          description: "EUID, for example FIFPRO.0116297-6"
          properties:
            value:
              type: string
              description: "EUID"
              minLength: 16
              maxLength: 16
            source:
              $ref: '#/components/schemas/Source'
        names:
          type: array
          description: "Company names; company name, parallel company names and auxiliary company names"
          items:
            $ref: '#/components/schemas/RegisterName'
          minItems: 0
        mainBusinessLine:
          type: object
          required: ["type", "source"]
          description: "Main line of business"
          properties:
            type:
              type: string
              description: "TOL 2008 code"
              minLength: 2
              maxLength: 5
            descriptions:
              type: array
              description: "TOL 2008 descriptions"
              items:
                $ref: '#/components/schemas/DescriptionEntry'
              minItems: 0
            typeCodeSet:
              type: string
              description: "Code lists TOIMI, TOIMI2 and TOIMI3 of the Standard Industrial Classification TOL 2008"
              minLength: 5
              maxLength: 6
            registrationDate:
              type: string
              nullable: true
              format: date
              description: "Start date of TOL 2008 code in the format yyyy-mm-dd"
              minLength: 10
              maxLength: 10
            source:
              $ref: '#/components/schemas/Source'
        website:
          type: object
          required: ["url", "source"]
          description: "Company's website"
          properties:
            url:
              type: string
              description: "Website"
              minLength: 0
              maxLength: 255
            registrationDate:
              type: string
              nullable: true
              format: date
              minLength: 10
              maxLength: 10
            source:
              $ref: '#/components/schemas/Source'
        companyForms:
          type: array
          description: "Company form and previous details, if any"
          items:
            $ref: '#/components/schemas/CompanyForm'
          minItems: 0
          maxItems: 2
        companySituations:
          type: array
          description: "Company situation (restructuring, liquidation or bankruptcy, if any)"
          items:
            $ref: '#/components/schemas/CompanySituation'
          minItems: 0
        registeredEntries:
          type: array
          description: "Company’s register entries"
          items:
            $ref: '#/components/schemas/RegisteredEntry'
          minItems: 0
        addresses:
          type: array
          description: "Company’s street or postal address"
          items:
            $ref: '#/components/schemas/Address'
          minItems: 0
          maxItems: 2
        tradeRegisterStatus:
          type: string
          description: >
            [Company status on the Finnish Trade Register](/opendata-ytj-api/v3/description?code=REK_KDI&lang=en)
        status:
          type: string
          description: >
            [Business ID status](/opendata-ytj-api/v3/description?code=STATUS3&lang=en)
        registrationDate:
          type: string
          nullable: true
          format: date
          description: "Date of registration of the company in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        endDate:
          type: string
          nullable: true
          minLength: 10
          maxLength: 10
          format: date
          description: "Date of dissolution in the format yyyy-mm-dd"
        lastModified:
          type: string
          minLength: 19
          maxLength: 19
          format: date-time
          x-field-extra-annotation: "@com.fasterxml.jackson.annotation.JsonFormat(shape = com.fasterxml.jackson.annotation.JsonFormat.Shape.STRING, pattern = \"yyyy-MM-dd HH:mm:ss\")"
          description: "Latest update, including seconds, without a time zone in the format ‘yyyy-mm-dd 00:00:00'"
    Address:
      type: object
      description: "Address details"
      required: ["type", "source"]
      properties:
        type:
          type: integer
          format: int32
          description: "Type of address, street address: 1, postal address: 2. "
        street:
          type: string
          nullable: true
          description: "Street address"
          minLength: 0
          maxLength: 50
        postCode:
          type: string
          nullable: true
          description: "Postal code"
          minLength: 0
          maxLength: 5
        postOffices:
          type: array
          description: "Town or city in various languages"
          items:
            $ref: '#/components/schemas/PostOffice'
          minItems: 0
        postOfficeBox:
          type: string
          nullable: true
          description: "PO Box"
          minLength: 0
          maxLength: 5
        buildingNumber:
          type: string
          nullable: true
          description: "Building"
          minLength: 0
          maxLength: 13
        entrance:
          type: string
          nullable: true
          description: "Entrance"
          minLength: 0
          maxLength: 13
        apartmentNumber:
          type: string
          nullable: true
          description: "Apartment"
          minLength: 0
          maxLength: 4
        apartmentIdSuffix:
          type: string
          nullable: true
          description: "Divider"
          minLength: 0
          maxLength: 1
        co:
          type: string
          nullable: true
          description: "C/o in the address"
          minLength: 0
          maxLength: 34
        country:
          type: string
          nullable: true
          description: "Two-letter country code"
          minLength: 0
          maxLength: 2
        freeAddressLine:
          type: string
          nullable: true
          description: "Free-format address for instance for an address outside Finland. Returns are replaced by spaces, spaces are replaced by underscores, such as in Norgårdsvägen_3 _ SE-451_75 Uddevalla."
          minLength: 0
          maxLength: 1000
        registrationDate:
          type: string
          nullable: true
          format : date
          description: "Date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        source:
          $ref: '#/components/schemas/Source'
    RegisterName:
      type: object
      description: "Name details"
      required: ["name", "type", "version", "source"]
      properties:
        name:
          type: string
          description: "Company name"
          minLength: 0
          maxLength: 1000
        type:
          type: string
          description: >
            [Type of name](/opendata-ytj-api/v3/description?code=TLAJI&lang=en)
          minLength: 1
          maxLength: 8
        registrationDate:
          type: string
          nullable: true
          format: date
          description: "Date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        endDate:
          type: string
          nullable: true
          format: date
          description: "End date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        version:
          type: integer
          format: int32
          description: "Version, 1 is the current version, other numbers are previous versions"
        source:
          $ref: '#/components/schemas/Source'
    CompanyForm:
      type: object
      required: ["type", "version", "source"]
      description: "Company form"
      properties:
        type:
          type: string
          description: >
            [Company form code](/opendata-ytj-api/v3/description?code=YRMU&lang=en)
          minLength: 1
          maxLength: 8
        descriptions:
          type: array
          description: "Company form descriptions"
          items:
            $ref: '#/components/schemas/DescriptionEntry'
          minItems: 0
        registrationDate:
          type: string
          nullable: true
          format: date
          description: "Date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        endDate:
          type: string
          nullable: true
          format: date
          description: "End date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        version:
          type: integer
          format: int32
          description: "Version, 1 is the current version, other numbers are previous versions"
        source:
          $ref: '#/components/schemas/Source'
    CompanySituation:
      type: object
      required: ["type", "source"]
      description: "Company situation (restructuring, liquidation or bankruptcy, if any)"
      properties:
        type:
          type: string
          description: >
            [Company situation code](/opendata-ytj-api/v3/description?code=SELTILA,SANE,KONK&lang=en)
          enum: ["SANE", "SELTILA", "KONK"]
        registrationDate:
          type: string
          nullable: true
          format: date
          description: "Date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        endDate:
          type: string
          nullable: true
          format: date
          description: "End date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        source:
          $ref: '#/components/schemas/Source'
    RegisteredEntry:
      type: object
      required: ["type", "register", "authority"] 
      description: "Register entries"
      properties:
        type:
          type: string
          description: >
            [Company registration status code](/opendata-ytj-api/v3/description?code=REK_KDI&lang=en). Must be interpreted in the REK_KDI code list by combining the register entry code with the register code separated by an underscore, such as in '1_0', indicating unregistered on the Finnish
          minLength: 1
          maxLength: 8
        descriptions:
          type: array
          description: "Registration status descriptions"
          items:
            $ref: '#/components/schemas/DescriptionEntry'
          minItems: 0
        registrationDate:
          type: string
          nullable: true
          format: date
          description: "Date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        endDate:
          type: string
          nullable: true
          format: date
          description: "End date of registration in the format yyyy-mm-dd"
          minLength: 10
          maxLength: 10
        register:
          type: string
          description: >
            [Register code](/opendata-ytj-api/v3/description?code=REK&lang=en)
          minLength: 1
          maxLength: 8
        authority:
          type: string
          description: >
            [Authority code](/opendata-ytj-api/v3/description?code=VIRANOM&lang=en)
          minLength: 1
          maxLength: 8
    Source:
      type: string
      description: >
        <a aria-label="Data source, opens in a new window" rel="noopener" href="/opendata-ytj-api/v3/description?code=TLAHDE&lang=en">Data source <svg width="15" height="14" viewBox="0 -9 24 24"> <path margin="0" fill="#035ca7" d="M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708"></path></svg></a>
    DescriptionEntry:
      type: object
      required: ["languageCode"]
      description: "Data description"
      properties:
        languageCode:
          type: string
          description: "Language code, 1 - Finnish, 2 - Swedish, 3 - English"
          maxLength: 2
        description:
          type: string
          description: "Code description"
          nullable: true
          maxLength: 255
    PostOffice:
      type: object
      required: ["city", "languageCode"]
      description: "Postal addresses"
      properties:
        city:
          type: string
          description: "Town or city"
          maxLength: 50
        languageCode:
          type: string
          description: >
            [Language code](/opendata-ytj-api/v3/description?code=KIELI&lang=en)
          maxLength: 8
        municipalityCode:
          type: string
          description: "Municipality code"
          nullable: true
          minLength: 3
          maxLength: 3
    PostOfficeEntry:
      type: object
      required: ["postCode", "city", "active", "languageCode"]
      description: "Postal addresses"
      properties:
        postCode:
          type: string
          description: "Postal code"
          minLength: 5
          maxLength: 5
        city:
          type: string
          description: "Town or city"
          maxLength: 50
        active:
          type: boolean
          description: "Is the detail active"
        languageCode:
          type: string
          description: >
            [Language code](/opendata-ytj-api/v3/description?code=KIELI&lang=en)
          maxLength: 8
        municipalityCode:
          type: string
          description: "Municipality code"
          nullable: true
          minLength: 3
          maxLength: 3
    ErrorResponse:
      type: object
      required: [ "timestamp", "code" ]
      description: "Error message"
      properties:
        timestamp:
          type: string
          minLength: 19
          maxLength: 19
          format: date-time
          x-field-extra-annotation: "@com.fasterxml.jackson.annotation.JsonFormat(shape = com.fasterxml.jackson.annotation.JsonFormat.Shape.STRING, pattern = \"yyyy-MM-dd HH:mm:ss\")"
          description: "Time, including seconds, without a time zone in the format ‘YYYY-MM-DD 00:00:00'"
        message:
          type: string
          description: "Error message"
          maxLength: 1000
        errorcode:
          type: integer
          format: int32
          description: "Error code"

externalDocs:
  description: "Find out more about the Swagger software"
  url: 'http://swagger.io'