duolingo4d

A most easily usable Duolingo API wrapper in Dart!

1. About

1. About #

Duolingo4D is an open-sourced Dart library.
With Duolingo4D, you can easily integrate your application with the Duolingo API.

Duolingo4D is an unofficial library.

Duolingo does not publish any official API references or specifications, so I reverse-engineered Duolingo by analyzing its communication content.

1.1. Supported Duolingo API #

	Auth Required	Remarks
Manifest	❌	You can get the manifest information of Duolingo.
Version Info	❌	You can fetch metadata about the various configurations of services in Duolingo.
Authentication	❌	Authenticate user by using Duolingo registered username or email address and password.
User	✅	You can fetch detailed user information.
Overview	✅	You can fetch information on all the words user have learned in Duolingo.
Word Hint	✅	You can fetch hint information about words and sentences.
Switch Language	✅	You can switch the learning language.
Activity	✅	You can get the activity of you and your friends in a ranking format.
Leaderboard	✅	You can get the information of leaderboard.
Dictionary	✅	You can get detailed information including discussions, audio and sample sentences associated with specific words.
Subscriptions	✅	You can get information on all friends associated with a user id.
Follow	✅	You can follow the account associated with the user ID specified in the argument.
Unfollow	✅	you can unfollow the account associated with the user ID specified in the argument.
Shop Items	✅	You can get a list of items that can be purchased in Duolingo.
Purchase	✅	You can purchase items sold in Duoligno by spending Lingots or Gems.
Alphabets	✅	You can get alphabet information for the learning language.
Stories	✅	You can get story information for the learning language.

1.2. Introduction #

1.2.1. Install Library #

With Dart:

 dart pub add duolingo4d

With Flutter:

 flutter pub add duolingo4d

1.2.2. Import It #

import 'package:duolingo4d/duolingo4d.dart';

1.2.3. Use Duolingo4D #

The easiest way to use it is to get a singleton instance from Duolingo and call each method.

All response entities returned from the methods of Duolingo contain status codes and header information when HTTP communication is performed in internal processing.

For example, when performing the authentication process for a user, it will look like this:

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  if (authResponse.status.isNotOk) {
    // Client or Server error or something.
    authResponse.status.reasonPhrase;
    authResponse.headers;
    return;
  }

  if (authResponse.hasError) {
    // When there is an error on authentication.
    final authError = authResponse.error!;
    print(authError.code);
    print(authError.reason);

    authError.isInvalidUser; // Returns true if user is invalid.
    authError.isInvalidPassword; // Returns true if password is invalid.
    return;
  }

  // Do something if user is authenticated.
}

1.3. Using #

1.3.1. Manifest #

Auth Required	Method	JSON
❌	manifest()	Check!

You can get the manifest information of Duolingo.

This manifest information includes information about Duolingo icons and the theme and background colors used by Duolingo.

void main() async {
  final duolingo = Duolingo.instance;

  final response = await duolingo.manifest();
  print(response);
}

1.3.2. Version Info API #

Auth Required	Method	JSON
❌	versionInfo()	Check!

The Version Info API allows you to fetch metadata about the configuration of Duolingo services.
This metadata includes the TTS data used to play back the audio of the words, as well as mapping information for the languages supported by Duolingo.

void main() async {
  final duolingo = Duolingo.instance;

  final versionInfoResponse = await duolingo.versionInfo();
  final ttsVoiceConfiguration = versionInfoResponse.ttsVoiceConfiguration;

  for (final voiceDirection in ttsVoiceConfiguration.voiceDirections) {
    print(voiceDirection.language);
    print(voiceDirection.voice);
  }
}

1.3.3. Authentication API #

Auth Required	Method	JSON
❌	authenticate({required String username, required String password})	Check!

You can use username and password to authenticate user registered with Duolingo. The registered e-mail address can be used for authentication in addition to the username.

In order to fetch the response you expect from each API that requires authentication, at first you need to use this authentication API to authenticate that the username and password entered are valid.

Note:
When a user is authenticated, the cookie information and session information for the Duolingo service is managed internally by Duolingo4D, so there is no need to be aware of this information after calling the API.

Caution:
If you try to authenticate again using information from an account that has already been authenticated, the Duolingo API will return an invalid password response.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  if (authResponse.status.isNotOk) {
    // Client or Server error or something.
    authResponse.status.reasonPhrase;
    authResponse.headers;
    return;
  }

  if (authResponse.hasError) {
    // When there is an error on authentication.
    final authError = authResponse.error!;
    print(authError.code);
    print(authError.reason);

    authError.isInvalidUser; // Returns true if user is invalid.
    authError.isInvalidPassword; // Returns true if password is invalid.
    return;
  }

  // Do something if user is authenticated.
}

1.3.4. User API #

Auth Required	Method	JSON
✅	user({required String userId})	Check!

From the User API, you can get detailed user information associated with the user ID.

The user ID is included in the response returned when the user authentication is completed. Please refer to the following implementation for details.

The user information also includes all the course information and skill information user have learned.

If user authentication has not been completed, data cannot be fetched.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final userResponse = await duolingo.user(userId: authResponse.userId);

  print(userResponse.name);
  print(userResponse.lingots);

  for (final course in userResponse.courses) {
    print(course.title);
    print(course.xp);
  }

  for (final skill in userResponse.currentCourse.skills) {
    if (skill.isAccessible) {
      print(skill.name);
      print(skill.proficiency);
      print(skill.tipsAndNotes);
    }
  }
}

1.3.5. Overview API #

Auth Required	Method	JSON
✅	overview()	Check!

From the Overview API, you can fetch information about all the words you have learned in the course you have selected. The details that can be retrieved about a word will vary depending on the course and word.

If user authentication has not been completed, data cannot be fetched.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final overviewResponse = await duolingo.overview();

  for (final vocabulary in overviewResponse.vocabularies) {
      print(vocabulary.word);
  }
}

1.3.6. Word Hint API #

Auth Required	Method	JSON
✅	wordHint({required String fromLanguage, required String learningLanguage, required String sentence})	Check!

You can fetch hint information for any word or sentence from the Word Hint API. Since the hint information is hint data managed by Duolingo, the accuracy of the translation data cannot be guaranteed.

The argument learningLanguage should be the language code corresponding to the word, and fromLanguage should be the language code corresponding to the hint. The sentence can be sentences as well as single words.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final wordHintResponse = await duolingo.wordHint(
    fromLanguage: 'en',
    learningLanguage: 'es',
    sentence: 'bolígrafos',
  );

  for (final token in wordHintResponse.tokens) {
    final headers = token.table.headers;
    for (final header in headers) {
      print(header.selected);
      print(header.token);
    }

    final rows = token.table.rows;
    for (final row in rows) {
      for (final cell in row.cells) {
        print(cell.hint);
      }
    }
  }
}

1.3.7. Switch Language API #

Auth Required	Method
✅	switchLanguage({required String fromLanguage, required String learningLanguage})

The Switch Language API allows you to switch between the courses supported by Duolingo. The mapping information for the courses that can be switched using the Switch Language API can be obtained from the Version Info API.

For the argument learningLanguage, specify the language to be learned after switching. And for fromLanguage, specify the language to be used when learning that learningLanguage.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final switchLanguageResponse = await duolingo.switchLanguage(
    fromLanguage: 'es',
    learningLanguage: 'en',
  );

  print(switchLanguageResponse.statusCode);
  print(switchLanguageResponse.reasonPhrase);
}

1.3.8. Activity API #

Auth Required	Method	JSON
✅	activity()	Check!

The Activity API allows you to get information about your ranking with friends who are following you on Duolingo. The Ranking provides the feature to sort in ascending or descending order by score item.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final activityResponse = await duolingo.activity();

  print(activityResponse.ranking);
  print(activityResponse.userIds);

  final ranking = activityResponse.ranking;

  // You can order ranking by score item.
  print(ranking.orderByScoreNameDesc());
  print(ranking.orderByScoreXpDesc());

  for (final score in ranking.scores) {
    print(score.userId);
    print(score.xp);
  }
}

1.3.9. Leaderboard API #

Auth Required	Method	JSON
✅	leaderboard({required String userId})	Check!

The Leaderboard API allows you to get information about leaderboard on Duolingo.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final leaderboardResponse =
      await duolingo.leaderboard(userId: authResponse.userId);
  print(leaderboardResponse);

  final ativeThread = leaderboardResponse.activeThread;
  print(ativeThread);
  print(ativeThread.cohort);

  for (final rank in ativeThread.cohort.ranks) {
    // You can get the leaderboard ranking in ascending order of score.
    print(rank);
  }
}

1.3.10. Dictionary API #

Auth Required	Method	JSON
✅	dictionary({required String wordId})	Check!

Dictionary API allows you to get detailed information including discussion information associated with a particular word, URL to audio data, and sample sentences.

Specifically, you can get the information on this page on the official Duolingo.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final dictionaryResponse = await duolingo.dictionary(
    wordId: 'cbdb71cdcf9e4715771206e1c0b0b94c',
  );

  print(dictionaryResponse);

  for (final alternativeForm in dictionaryResponse.alternativeForms) {
    print(alternativeForm);
  }

  for (final discussion in dictionaryResponse.relatedDiscussions) {
    print(discussion);
  }

  for (final lexeme in dictionaryResponse.relatedLexemes) {
    print(lexeme);
  }
}

1.3.11. Subscriptions API #

Auth Required	Method	JSON
✅	subscriptions({required String userId})	Check!

From Subscriptions API, you can get information on all friends associated with a user id.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final subscriptionsResponse = await duolingo.subscriptions(userId: 'xxxxxx');
  print(subscriptionsResponse);

  for (final friend in subscriptionsResponse.friends) {
    print(friend);
  }
}

1.3.12. Follow API #

Auth Required	Method
✅	follow({required String userId, required String targetUserId})

With Follow API, you can follow the account associated with the user ID specified in the argument.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final followResponse = await duolingo.follow(
    userId: authResponse.userId,
    targetUserId: 'user_id_to_follow',
  );

  print(followResponse);
}

1.3.13. Unfollow API #

Auth Required	Method
✅	unfollow({required String userId, required String targetUserId})

With Unfollow API, you can unfollow the account associated with the user ID specified in the argument.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final unfollowResponse = await duolingo.unfollow(
    userId: authResponse.userId,
    targetUserId: 'user_id_to_unfollow',
  );

  print(unfollowResponse);
}

1.3.14. Shop Items API #

Auth Required	Method	JSON
✅	shopItems()	Check!

From Shop Items API, you can get a list of items that can be purchased in Duolingo.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final shopItemsResponse = await duolingo.shopItems();

  for (final product in shopItemsResponse.products) {
    print(product);
  }
}

1.3.15. Purchase API #

Auth Required	Method	JSON
✅	purchase({required String itemId, required String userId, required String learningLanguage})	Check!

With Purchase API, you can purchase items sold in Duoligno by spending Lingots or Gems.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final userResponse = await duolingo.user(userId: authResponse.userId);
  final shopItemsResponse = await duolingo.shopItems();

  final response = await duolingo.purchase(
    itemId: shopItemsResponse.products[0].id,
    userId: userResponse.id,
    learningLanguage: userResponse.learningLanguage,
  );

  print(response);

  if (response.isNotEstablished) {
    // It indicates purchase request was failed.
    return;
  }
}

1.3.16. Alphabets API #

Auth Required	Method	JSON
✅	alphabets({required String fromLanguage, required String learningLanguage})	Check!

With Alphabets API, you can get alphabet information for the learning language.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final alphabetsResponse = await duolingo.alphabets(
    fromLanguage: 'en',
    learningLanguage: 'ja',
  );

  print(alphabetsResponse);

  for (final alphabet in alphabetsResponse.alphabets) {
    print(alphabet);

    for (final group in alphabet.groups) {
      print(group);

      for (final character in group.characters) {
        if (character.isEmpty) {
          // The empty state of this character indicates a space
          // in the alphabetic table.
          continue;
        }

        print(character.value);
        print(character.transliteration);
        print(character.ttsUrl);
        print(character.proficiency);
      }
    }
  }
}

1.3.17. Stories API #

Auth Required	Method	JSON
✅	stories({required String fromLanguage, required String learningLanguage, IllustrationFormat format = IllustrationFormat.svg})	Check!

With Stories API, you can get story information for the learning language.

void main() async {
  final duolingo = Duolingo.instance;

  final authResponse = await duolingo.authenticate(
    username: 'test_username',
    password: 'test_password',
  );

  final storiesResponse = await duolingo.stories(
    fromLanguage: 'en',
    learningLanguage: 'ja',
    // You can select format in SVG, PNG and PDF.
    // The default is SVG.
    format: IllustrationFormat.png,
  );

  print(storiesResponse);

  for (final story in storiesResponse.stories) {
    print(story);
  }
}

1.4. License #

Copyright (c) 2021, Kato Shinya. All rights reserved.
Use of this source code is governed by a
BSD-style license that can be found in the LICENSE file.

1.5. More Information #

Duolingo4D was designed and implemented by Kato Shinya.

duolingo4d 0.3.0
duolingo4d: ^0.3.0 copied to clipboard

Metadata

1. About #

1.1. Supported Duolingo API #

1.2. Introduction #

1.2.1. Install Library #

1.2.2. Import It #

1.2.3. Use Duolingo4D #

1.3. Using #

1.3.1. Manifest #

1.3.2. Version Info API #

1.3.3. Authentication API #

1.3.4. User API #

1.3.5. Overview API #

1.3.6. Word Hint API #

1.3.7. Switch Language API #

1.3.8. Activity API #

1.3.9. Leaderboard API #

1.3.10. Dictionary API #

1.3.11. Subscriptions API #

1.3.12. Follow API #

1.3.13. Unfollow API #

1.3.14. Shop Items API #

1.3.15. Purchase API #

1.3.16. Alphabets API #

1.3.17. Stories API #

1.4. License #

1.5. More Information #

← Metadata

Publisher

Metadata

License

Dependencies

More

duolingo4d 0.3.0 duolingo4d: ^0.3.0 copied to clipboard

Metadata

1. About #

1.1. Supported Duolingo API #

1.2. Introduction #

1.2.1. Install Library #

1.2.2. Import It #

1.2.3. Use Duolingo4D #

1.3. Using #

1.3.1. Manifest #

1.3.2. Version Info API #

1.3.3. Authentication API #

1.3.4. User API #

1.3.5. Overview API #

1.3.6. Word Hint API #

1.3.7. Switch Language API #

1.3.8. Activity API #

1.3.9. Leaderboard API #

1.3.10. Dictionary API #

1.3.11. Subscriptions API #

1.3.12. Follow API #

1.3.13. Unfollow API #

1.3.14. Shop Items API #

1.3.15. Purchase API #

1.3.16. Alphabets API #

1.3.17. Stories API #

1.4. License #

1.5. More Information #

← Metadata

Publisher

Metadata

License

Dependencies

More

duolingo4d 0.3.0
duolingo4d: ^0.3.0 copied to clipboard