pyungyo-com Plans API

openapi: 3.2.0
info:
  title: 평생요금제닷컴 알뜰폰 요금제 Plans API
  version: 2.1.0
  description: '한국 알뜰폰(MVNO) 요금제를 통신사 공식 홈페이지 기준(하루 5번 확인)으로 조회합니다. 인증 없음·읽기 전용. 출처 표기(CC BY 4.0): "평생요금제닷컴(pyungyo.com) 집계, 기준 시각". 가입 전 통신사 화면에서 최종 금액을 확인하세요.'
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/deed.ko
  contact:
    url: https://pyungyo.com/about/
servers:
- url: https://pyungyo.com
tags:
- name: Plans
paths:
  /api/v1/plans:
    get:
      operationId: searchPlans
      summary: 조건으로 요금제 검색 (월 요금 낮은 순·데이터 많은 순)
      description: 데이터 GB·월 요금 상한·통신망(SKT/KT/LGU)·5G·통화 무제한·부가통화·유심 무료·테더링·결합·데이터 쉐어링·조건 없음·통신사·종류(평생/기간/선착순)로 거른 요금제를 월 요금 낮은 순(sort=data 면 데이터 많은 순)으로 최대 50개 돌려줍니다. 기본은 평생 할인·정가(type=lifetime)만. comparePeriod=true 면 같은 조건의 기간 할인 요금제(할인 종료 후 인상 요금·24개월 총액)와 비교도 함께. 결과 요금제의 id 로 /api/v1/plans/{id} 를 부르면 세부 조건·가격 기록이 나옵니다.
      parameters:
      - name: type
        in: query
        required: false
        description: lifetime=평생 할인·정가(기본) / limited=선착순·기한 한정 가입 / period=N개월 기간 할인 / nodate=종료일 안 적힌 할인 / all=전부
        schema:
          type: string
          enum:
          - lifetime
          - limited
          - period
          - nodate
          - all
      - name: dataMin
        in: query
        required: false
        description: 한 달 데이터 최소 GB (매일 제공은 30일치로 계산, 무제한 포함)
        schema:
          type: number
      - name: dataUnlimited
        in: query
        required: false
        description: 데이터 무제한만
        schema:
          type: boolean
      - name: dailyData
        in: query
        required: false
        description: '매일 추가 데이터(예: 매일 2GB)를 따로 주는 요금제만'
        schema:
          type: boolean
      - name: qosMin
        in: query
        required: false
        description: '데이터 다 쓴 뒤 최소 속도 kbps (예: 1000=1Mbps, 3000=3Mbps, 5000=5Mbps)'
        schema:
          type: number
      - name: feeMax
        in: query
        required: false
        description: 월 요금 상한(원, VAT 포함)
        schema:
          type: number
      - name: mno
        in: query
        required: false
        description: 빌려 쓰는 통신망
        schema:
          type: string
          enum:
          - SKT
          - KT
          - LGU
      - name: network
        in: query
        required: false
        description: network
        schema:
          type: string
          enum:
          - LTE
          - 5G
      - name: voiceUnlimited
        in: query
        required: false
        description: 통화 무제한만
        schema:
          type: boolean
      - name: voiceMin
        in: query
        required: false
        description: 통화 최소 분
        schema:
          type: number
      - name: smsUnlimited
        in: query
        required: false
        description: 문자 무제한만
        schema:
          type: boolean
      - name: extraCallMin
        in: query
        required: false
        description: '부가통화(전국대표번호 15XX·050·영상통화)를 따로 이 분 이상 주는 요금제만 — 공식 화면에 분이 적힌 것만 (예: 300)'
        schema:
          type: number
      - name: usimFree
        in: query
        required: false
        description: 요금제에 "유심 무료"가 공식 원문으로 적힌 요금제만
        schema:
          type: boolean
      - name: tetheringMin
        in: query
        required: false
        description: 공식 홈페이지에 테더링(핫스팟) 한도가 적힌 요금제 중 한 달 테더링 가능 최소 GB (1=테더링 한도 표시 전체)
        schema:
          type: number
      - name: bundle
        in: query
        required: false
        description: 결합 혜택 원문이 있는 요금제 (internet=인터넷·유선 결합, mobile=가족·모바일 결합, any=둘 중 하나 이상)
        schema:
          type: string
          enum:
          - internet
          - mobile
          - any
      - name: dataSharing
        in: query
        required: false
        description: 데이터 쉐어링 가능 원문이 적힌 요금제만
        schema:
          type: boolean
      - name: noCondition
        in: query
        required: false
        description: 최소 사용량·개통 초기 유지 기간 등 가입 조건이 하나도 없는 요금제만
        schema:
          type: boolean
      - name: brand
        in: query
        required: false
        description: '알뜰폰 통신사 이름 일부 (예: 이야기, 프리티, 헬로)'
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: fee=월 요금 낮은 순(기본), data=데이터 많은 순, total24=24개월 총액 낮은 순(기간할인 포함 비교 시)
        schema:
          type: string
          enum:
          - fee
          - data
          - total24
      - name: comparePeriod
        in: query
        required: false
        description: true 로 주면 같은 조건의 기간 할인(프로모션) 최저가·할인 종료 후 인상 요금·24개월 총액 비교(periodComparison)를 함께 돌려줍니다
        schema:
          type: boolean
      - name: limit
        in: query
        required: false
        description: 1~50, 기본 10
        schema:
          type: number
      - name: format
        in: query
        required: false
        description: text 로 주면 사람이 읽는 글(text/plain)
        schema:
          type: string
          enum:
          - json
          - text
      responses:
        '200':
          description: 검색 결과
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: string
                    description: 출처
                  attribution:
                    type: string
                    description: 인용 표기
                  license:
                    type: string
                    description: 이용 조건(CC BY 4.0)
                  asOf:
                    type: string
                    description: 기준 시각(UTC ISO)
                  total:
                    type: number
                    description: 조건에 맞는 개수
                  plans:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plan'
            text/plain:
              schema:
                type: string
      tags:
      - Plans
  /api/v1/plans/{id}:
    get:
      operationId: getPlan
      summary: 요금제 하나 (세부 조건·가격 기록·고객센터)
      description: '요금제 하나의 전체 기록: 월 요금·데이터·소진 후 처리·통화·문자·부가통화·테더링·유심비·결합·데이터 쉐어링·가입 조건(통신사 원문 그대로)·근거 문구·확인 시각·가격 기록(2026-09-19부터 매일)·통신사 고객센터. id 는 search 나 plans 결과의 id. 목록에서 빠진 요금제는 status=retired 와 마지막 확인 기록·대안 요금제로 응답하므로 404 가 아닙니다.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: text 로 주면 사람이 읽는 글(text/plain)
        schema:
          type: string
          enum:
          - json
          - text
      responses:
        '200':
          description: 요금제. 목록에서 빠진 요금제(180일 안)는 plan=null, status="retired", retired{lastSeenDate, lastKnown{fee,kind}(그때 기록·지금 요금 아님), successor(새 번호로 살아 있으면), alternatives, sameNetwork, priceHistory} 로 응답
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: string
                    description: 출처
                  attribution:
                    type: string
                    description: 인용 표기
                  license:
                    type: string
                    description: 이용 조건(CC BY 4.0)
                  asOf:
                    type: string
                    description: 기준 시각(UTC ISO)
                  plan:
                    $ref: '#/components/schemas/Plan'
                  status:
                    type: string
                    description: 빠진 요금제면 "retired"
                  retired:
                    type: object
                    description: 빠진 요금제 기록
            text/plain:
              schema:
                type: string
        '404':
          description: 한 번도 게시된 적 없는 id (또는 빠진 지 180일 지남)
      tags:
      - Plans
  /api/v1/plans/{id}/history:
    get:
      operationId: getPlanPriceHistory
      summary: 요금제 가격 기록
      description: 그 요금제의 월 요금이 날마다 어땠는지(2026-09-19 기록 시작) 바뀐 날짜와 요금만 추려 돌려줍니다. "지금 요금이 언제부터인지", "요금이 올랐나 내렸나"에 답할 때 씁니다. 가격 기록은 통신사 공식 홈페이지 게시값을 매일 보관한 것입니다.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 가격 기록 (빠진 요금제는 status="retired" 와 함께 남은 기록)
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: string
                    description: 출처
                  attribution:
                    type: string
                    description: 인용 표기
                  license:
                    type: string
                    description: 이용 조건(CC BY 4.0)
                  asOf:
                    type: string
                    description: 기준 시각(UTC ISO)
                  history:
                    type: object
                    description: recordStart·points[{date,fee}]
            text/plain:
              schema:
                type: string
        '404':
          description: 한 번도 게시된 적 없는 id
      tags:
      - Plans
components:
  schemas:
    Plan:
      type: object
      properties:
        id:
          type: string
          description: 요금제 id
        type:
          type: string
          description: lifetime=평생 할인 · flat=정가 · limited=한정 가입 · period=기간 할인 · nodate=종료일 없는 할인
        brand:
          type: string
          description: 알뜰폰 통신사
        name:
          type: string
          description: 요금제 이름(통신사 표기 그대로)
        mno:
          type: string
          description: 통신망 SKT·KT·LGU
        network:
          type: string
          description: LTE·5G
        fee:
          type: number
          description: 월 요금(원, VAT 포함)
        listFee:
          type: number
          description: 정가
        promoMonths:
          type:
          - number
          - 'null'
          description: 기간 할인 개월
        afterFee:
          type:
          - number
          - 'null'
          description: 기간 할인 뒤 요금
        dataGb:
          type:
          - number
          - 'null'
          description: 기본 데이터 GB
        dailyDataGb:
          type: number
          description: 매일 데이터 GB
        dataUnlimited:
          type: boolean
          description: 데이터 무제한
        qosKbps:
          type: number
          description: 다 쓴 뒤 속도 kbps
        voiceMin:
          type:
          - number
          - 'null'
          description: 통화 분
        voiceUnlimited:
          type: boolean
          description: 통화 무제한
        smsCount:
          type:
          - number
          - 'null'
          description: 문자 건
        smsUnlimited:
          type: boolean
          description: 문자 무제한
        extraCallKind:
          type:
          - string
          - 'null'
          description: 부가통화 구분(separate=따로 제공, included=기본통화 내, none=과금)
        extraCallMin:
          type:
          - number
          - 'null'
          description: 부가통화 별도 제공 분
        usimFree:
          type: boolean
          description: 요금제 원문 유심 무료 여부
        tetheringGb:
          type: number
          description: 테더링 가능 한도 GB (0=미표시·불가)
        bundleInternet:
          type: boolean
          description: 인터넷 결합 혜택 표시 여부
        bundleMobile:
          type: boolean
          description: 가족·모바일 결합 혜택 표시 여부
        dataSharing:
          type: boolean
          description: 데이터 쉐어링 가능 표시 여부
        noCondition:
          type: boolean
          description: 의무사용·유지기간 등 가입 조건 없음 여부
        signupUntil:
          type:
          - string
          - 'null'
          description: 가입 기한(한정)
        feeSince:
          type: string
          description: 지금 요금이 시작된 날
        evidence:
          type: string
          description: 통신사 화면 원문 근거
        sourceUrl:
          type: string
          description: 통신사 공식 주소
        pageUrl:
          type: string
          description: 평생요금제닷컴 상세 주소
        checkedAt:
          type: string
          description: 확인 시각
        verification:
          type: object
          description: '기계 대조 결과 — 매일 10:30 게시 직후 PC 가 통신사 공식 화면을 열어 게시값과 한 글자씩 대조한 결과. status: match(대조한 칸 전부 일치) · mismatch(불일치 칸 있음, 원인 확인 중이거나 소비자에게 덜 유리한 값을 실은 경우) · partial(일치 칸은 있으나 못 찾은 칸도 있음) · unchecked(기계 미확인 — 대조 기록이 없거나 3일 넘게 오래됨). 요금제 하나 조회에서만 제공.'
          properties:
            status:
              type: string
              description: match | mismatch | partial | unchecked
            label:
              type: string
              description: '사람이 읽는 한 줄 (예: "기계 대조 일치 (10칸)", "기계 미확인")'
            checkedAt:
              type:
              - string
              - 'null'
              description: 대조 시각(ISO)
            matched:
              type: integer
              description: 일치한 칸 수
            mismatched:
              type: integer
              description: 불일치 칸 수
            notFound:
              type: integer
              description: 화면에서 못 찾은 칸 수
            method:
              type: string
              description: 대조 방법
            detail:
              type: string
              description: 대조 방법·결과 공개 페이지 주소
externalDocs:
  url: https://pyungyo.com/developers/