WIA-LANG-001 API는 RESTful 아키텍처를 기반으로 하는 개방형 언어 보존 인터페이스입니다. 이 API를 통해 개발자는 멸종위기 언어 데이터에 접근하고, 새로운 데이터를 추가하며, 언어 분석 도구를 통합할 수 있습니다. 모든 엔드포인트는 HTTPS를 통해 보호되며, OAuth 2.0 인증을 지원합니다.
WIA-LANG API는 OAuth 2.0 프로토콜을 사용하여 안전한 인증을 제공합니다. 弘益人間 정신에 따라 읽기 API는 무료로 공개되며, 쓰기 작업은 인증이 필요합니다.
// API 키 발급 (개발자 포털에서 발급)
const WIA_API_KEY = 'wia_lang_key_abc123def456';
const WIA_API_SECRET = 'secret_xyz789';
// API 클라이언트 초기화
import { WIALangClient } from '@wia/lang-client';
const client = new WIALangClient({
apiKey: WIA_API_KEY,
apiSecret: WIA_API_SECRET,
baseUrl: 'https://api.wia.org/v1',
philosophy: '弘益人間'
});
// OAuth 2.0 인증 토큰 발급
const authResponse = await client.authenticate();
console.log('Access Token:', authResponse.accessToken);
console.log('Expires In:', authResponse.expiresIn);
// 인증된 요청 예제
const languages = await client.getLanguages({
endangermentLevel: 'critically_endangered',
limit: 10
});| 권한 레벨 | 설명 | 허용 작업 | 요청 제한 |
|---|---|---|---|
| Public | 인증 불필요 | 읽기 전용 (GET) | 100 req/hour |
| Contributor | 커뮤니티 기여자 | 데이터 추가, 수정 제안 | 1,000 req/hour |
| Linguist | 언어학자 | 검증된 데이터 입력 | 5,000 req/hour |
| Administrator | 시스템 관리자 | 모든 작업 (삭제 포함) | 무제한 |
/v1/languages
설명: 모든 언어 목록 조회 (페이지네이션 지원)
// 요청 예제
GET https://api.wia.org/v1/languages?page=1&limit=20&endangermentLevel=critically_endangered
// 쿼리 파라미터
{
"page": 1, // 페이지 번호 (기본값: 1)
"limit": 20, // 페이지당 항목 수 (기본값: 20, 최대: 100)
"endangermentLevel": "critically_endangered", // 멸종위기 등급 필터
"region": "Asia", // 지역 필터
"hasAudio": true, // 오디오 데이터 존재 여부
"sortBy": "speakerCount", // 정렬 기준
"sortOrder": "desc" // 정렬 방향 (asc/desc)
}
// 응답 예제
{
"status": "success",
"data": {
"languages": [
{
"id": "lang-jje-001",
"code": "jje",
"name": "제주어",
"englishName": "Jeju Language",
"endangermentLevel": "critically_endangered",
"speakerCount": 5000,
"region": {
"country": "대한민국",
"province": "제주특별자치도"
},
"lastUpdated": "2025-12-29T12:00:00Z",
"dataQuality": {
"completeness": 85,
"hasAudio": true,
"hasGrammar": true,
"lexiconSize": 2500
},
"links": {
"self": "https://api.wia.org/v1/languages/lang-jje-001",
"lexicon": "https://api.wia.org/v1/languages/lang-jje-001/lexicon",
"audio": "https://api.wia.org/v1/languages/lang-jje-001/audio"
}
}
],
"pagination": {
"currentPage": 1,
"totalPages": 15,
"totalItems": 300,
"itemsPerPage": 20,
"hasNext": true,
"hasPrevious": false
}
},
"meta": {
"philosophy": "弘益人間",
"version": "1.0",
"timestamp": "2025-12-29T14:30:00Z"
}
}/v1/languages/{languageId}
설명: 특정 언어의 상세 정보 조회
// 요청 예제
GET https://api.wia.org/v1/languages/lang-jje-001
// 응답 예제
{
"status": "success",
"data": {
"id": "lang-jje-001",
"wiaLangVersion": "1.0",
"metadata": {
"languageCode": "jje",
"languageName": "제주어",
"englishName": "Jeju Language",
"alternativeNames": ["Jejueo", "Cheju"],
"endangermentLevel": "critically_endangered",
"speakerCount": 5000,
"region": {
"country": "대한민국",
"province": "제주특별자치도",
"coordinates": {
"latitude": 33.4996,
"longitude": 126.5312
}
},
"contributors": [
{
"name": "강영봉",
"role": "언어학자",
"affiliation": "제주대학교 국어문화원",
"contributionCount": 1250
}
],
"license": "CC-BY-SA-4.0",
"philosophy": "弘益人間"
},
"statistics": {
"lexiconSize": 2500,
"audioRecordings": 1800,
"videoRecordings": 150,
"documentCount": 320,
"lastActivity": "2025-12-28T18:45:00Z"
}
}
}/v1/languages/{languageId}/lexicon
설명: 특정 언어의 어휘 목록 조회
// 요청 예제
GET https://api.wia.org/v1/languages/lang-jje-001/lexicon?search=하르방&hasAudio=true
// 응답 예제
{
"status": "success",
"data": {
"languageId": "lang-jje-001",
"languageName": "제주어",
"words": [
{
"id": "word-jje-001",
"lemma": "하르방",
"translation": "할아버지",
"englishTranslation": "grandfather",
"partOfSpeech": "noun",
"pronunciation": {
"ipa": "haɾɯbaŋ",
"romanization": "hareubang"
},
"audio": {
"url": "https://cdn.wia.org/audio/jje/001.mp3",
"duration": 1.2,
"speaker": "speaker-042"
},
"usageFrequency": "common",
"culturalSignificance": "high",
"createdAt": "2025-11-15T10:20:00Z"
}
],
"pagination": {
"currentPage": 1,
"totalItems": 2500
}
}
}/v1/languages/{languageId}/lexicon
설명: 새로운 어휘 항목 추가 (인증 필요)
// 요청 예제
POST https://api.wia.org/v1/languages/lang-jje-001/lexicon
Authorization: Bearer {access_token}
Content-Type: application/json
{
"lemma": "고망",
"translation": "고맙다",
"englishTranslation": "thank you",
"partOfSpeech": "adjective",
"pronunciation": {
"ipa": "komaŋ",
"romanization": "gomang"
},
"semantics": {
"definition": "감사함을 표현하는 제주어",
"culturalContext": "일상 대화에서 자주 사용",
"examples": [
{
"sentence": "고망수다",
"translation": "고맙습니다"
}
]
},
"contributor": {
"name": "김제주",
"email": "jeju@example.com"
},
"philosophy": "弘益人間"
}
// 응답 예제
{
"status": "success",
"data": {
"id": "word-jje-2501",
"lemma": "고망",
"status": "pending_review",
"message": "어휘 항목이 성공적으로 제출되었습니다. 언어학자 검토 후 승인됩니다.",
"reviewUrl": "https://api.wia.org/v1/reviews/word-jje-2501"
},
"meta": {
"philosophy": "弘益人間 - 커뮤니티 기여에 감사드립니다"
}
}/v1/languages/{languageId}/audio
설명: 오디오 녹음 파일 업로드
// 멀티파트 폼 데이터로 업로드
POST https://api.wia.org/v1/languages/lang-jje-001/audio
Authorization: Bearer {access_token}
Content-Type: multipart/form-data
{
"file": [오디오 파일 바이너리],
"wordId": "word-jje-001",
"speaker": {
"id": "speaker-042",
"age": 68,
"gender": "female",
"nativeSpeaker": true,
"dialectRegion": "서귀포"
},
"transcription": {
"orthographic": "하르방",
"ipa": "haɾɯbaŋ",
"notes": "자연스러운 발음"
},
"recordingInfo": {
"date": "2025-12-29",
"equipment": "Zoom H6",
"environment": "controlled_studio"
}
}
// 응답 예제
{
"status": "success",
"data": {
"audioId": "audio-jje-1801",
"url": "https://cdn.wia.org/audio/jje/1801.flac",
"format": "FLAC",
"duration": 1.2,
"fileSize": 245000,
"checksum": "sha256:abc123...",
"processingStatus": "completed",
"waveformUrl": "https://cdn.wia.org/waveform/jje/1801.png"
}
}/v1/analyze/text
설명: 텍스트 언어 분석 및 자동 번역
// 요청 예제
POST https://api.wia.org/v1/analyze/text
Content-Type: application/json
{
"text": "하르방이 말씀하시다",
"sourceLanguage": "jje",
"targetLanguage": "ko",
"analysisType": ["morphology", "translation", "pronunciation"],
"includeAudio": true
}
// 응답 예제
{
"status": "success",
"data": {
"sourceText": "하르방이 말씀하시다",
"detectedLanguage": "jje",
"morphology": [
{
"word": "하르방",
"lemma": "하르방",
"pos": "noun",
"meaning": "할아버지"
},
{
"word": "이",
"lemma": "이",
"pos": "particle",
"function": "subject_marker"
},
{
"word": "말씀하시다",
"lemma": "말씀하다",
"pos": "verb",
"honorific": true
}
],
"translation": {
"ko": "할아버지가 말씀하시다",
"en": "Grandfather is speaking"
},
"pronunciation": {
"ipa": "haɾɯbaŋi malssɯmhasida",
"audioUrl": "https://api.wia.org/tts/jje?text=하르방이+말씀하시다"
}
}
}/v1/statistics/global
설명: 전체 언어 보존 통계
// 응답 예제
{
"status": "success",
"data": {
"totalLanguages": 7168,
"endangeredLanguages": 3018,
"criticallyEndangered": 578,
"totalWords": 15420000,
"audioRecordings": 8920000,
"contributors": 45230,
"countriesCovered": 195,
"byRegion": {
"Asia": 3521,
"Africa": 2139,
"Americas": 1062,
"Pacific": 1313,
"Europe": 133
},
"recentActivity": {
"newLanguages": 12,
"newWords": 8450,
"newAudio": 2340,
"period": "last_30_days"
},
"philosophy": "弘益人間 - 함께 보존하는 인류의 언어 유산"
}
}WIA-LANG API는 표준 HTTP 상태 코드를 사용하여 요청의 성공 또는 실패를 나타냅니다.
| 상태 코드 | 설명 | 예시 상황 |
|---|---|---|
| 200 OK | 요청 성공 | 데이터 조회 성공 |
| 201 Created | 리소스 생성 성공 | 새 어휘 항목 추가 |
| 400 Bad Request | 잘못된 요청 | 필수 필드 누락 |
| 401 Unauthorized | 인증 실패 | 유효하지 않은 API 키 |
| 403 Forbidden | 권한 없음 | 관리자 전용 작업 |
| 404 Not Found | 리소스 없음 | 존재하지 않는 언어 ID |
| 429 Too Many Requests | 요청 한도 초과 | Rate Limit 도달 |
| 500 Internal Server Error | 서버 오류 | 예상치 못한 서버 문제 |
// 에러 응답 예제
{
"status": "error",
"error": {
"code": "INVALID_LANGUAGE_CODE",
"message": "제공된 언어 코드가 ISO 639-3 표준에 맞지 않습니다",
"details": {
"field": "languageCode",
"value": "invalid",
"expected": "3-letter ISO 639-3 code"
},
"documentation": "https://docs.wia.org/api/errors#INVALID_LANGUAGE_CODE"
},
"meta": {
"requestId": "req-abc123",
"timestamp": "2025-12-29T14:30:00Z"
}
}WIA-LANG API는 다양한 프로그래밍 언어로 작성된 공식 SDK를 제공합니다.
// 설치
npm install @wia/lang-client
// 사용 예제
import { WIALangClient, EndangermentLevel } from '@wia/lang-client';
const client = new WIALangClient({
apiKey: process.env.WIA_API_KEY,
philosophy: '弘益人間'
});
// 타입 안전 언어 조회
const languages = await client.languages.list({
endangermentLevel: EndangermentLevel.CriticallyEndangered,
region: 'Asia',
hasAudio: true,
page: 1,
limit: 20
});
console.log(`발견된 언어: ${languages.data.length}`);
for (const lang of languages.data) {
console.log(`${lang.name} (${lang.code}): ${lang.speakerCount}명`);
// 어휘 조회
const lexicon = await client.lexicon.list(lang.id, {
limit: 10
});
console.log(` 어휘 항목: ${lexicon.pagination.totalItems}개`);
}
// 새 어휘 추가
const newWord = await client.lexicon.create('lang-jje-001', {
lemma: '바당',
translation: '바다',
englishTranslation: 'sea',
partOfSpeech: 'noun',
pronunciation: {
ipa: 'padaŋ'
}
});
console.log(`새 단어 추가됨: ${newWord.id}`);# 설치
pip install wia-lang-client
# 사용 예제
from wia_lang import WIALangClient, EndangermentLevel
client = WIALangClient(
api_key='your_api_key',
philosophy='弘益人間'
)
# 언어 조회
languages = client.languages.list(
endangerment_level=EndangermentLevel.CRITICALLY_ENDANGERED,
region='Asia',
has_audio=True,
page=1,
limit=20
)
print(f"발견된 언어: {len(languages.data)}")
for lang in languages.data:
print(f"{lang.name} ({lang.code}): {lang.speaker_count}명")
# 어휘 조회
lexicon = client.lexicon.list(lang.id, limit=10)
print(f" 어휘 항목: {lexicon.pagination.total_items}개")
# 오디오 업로드
with open('recording.flac', 'rb') as audio_file:
result = client.audio.upload(
language_id='lang-jje-001',
word_id='word-jje-001',
file=audio_file,
speaker={
'age': 68,
'gender': 'female',
'native_speaker': True
}
)
print(f"오디오 업로드 완료: {result.url}")WIA-LANG API는 웹훅을 통해 실시간 이벤트 알림을 제공합니다.
language.created - 새 언어 추가됨word.created - 새 어휘 추가됨word.approved - 어휘 검토 승인됨audio.uploaded - 오디오 업로드 완료language.status_changed - 멸종위기 등급 변경// 웹훅 페이로드 예제
{
"event": "word.created",
"timestamp": "2025-12-29T14:30:00Z",
"data": {
"wordId": "word-jje-2501",
"languageId": "lang-jje-001",
"lemma": "고망",
"contributor": "김제주",
"status": "pending_review"
},
"philosophy": "弘益人間"
}