WebService::MyGengo::Client - Client for interacting with the myGengo API
A perl library for accessing the MyGengo (http://mygengo.com) API.
use WebService::MyGengo::Client; my $client = WebService::MyGengo::Client->new({ public_key => 'pubkey' , private_key => 'privkey' , use_sandbox => 1 }); # Alternative constructor syntax $client = WebService::MyGengo::Client->new('pubkey', 'privkey', $use_sandbox); # A WebService::MyGengo::Job my $job = $client->get_job( 123 ); # Seeing what went wrong by inspecting the `last_response` unless ( $job = $client->get_job( "BLARGH!" ) ) { MyApp::Exception->throw({ message => "Oops: ".$client->last_response->message }); }
All attributes are read-only unless otherwise specified.
If you need a Client with different parameters, just create a new one :)
Your public API key.
Your private API key.
A boolean flag that determines whether to use the API sandbox or the live site.
The URI to be used as the base for all API endpoints.
This value is set automatically according to the use_sandbox attribute.
eg, 'http://api.sandbox.mygengo.com/v1.1'
A read-write flag indicating whether to dump debugging information to STDERR.
This is a semi-private attribute, as most people won't use it.
You can use _set_user_agent to supply your own UserAgent object to be used for API calls, eg LWPx::ParanoidAgent.
The agent must pass the `->isa('LWP::UserAgent')` test.
In DEBUG mode, a request_send and request_done handler will be registered with the agent to dump raw requests and responses.
A WebService::MyGengo::RequestFactory instance used to generate API requests.
The last raw response object received from the API.
Unless otherwise specified, all methods will:
You can retrieve the last raw response via the `last_response` attribute to inspect any specific error conditions. See the SYNOPSIS.
Returns the WebService::MyGengo::Account associated with your API keys.
Calls get_account_stats and get_account_balance internally to gather the parameters necessary to construct the Account object.
Returns a reference to a hash of account statistics.
You may find it easier to simply use get_account.
See: http://mygengo.com/api/developer-docs/methods/account-stats-get/
Returns a reference to a hash of account balance information.
See: http://mygengo.com/api/developer-docs/methods/account-balance-get/
Retrieves a job from myGengo with the specified id.
If $get_comments is true, additional API calls will be made to populate the Job's `comments` list.
If $get_revisions is true, additional API calls will be made to populate the Job's `revisions` list.
If $get_feedback is true, an additional API call will be made to populate the Job's `feedback` attribute.
Returns a WebService::MyGengo::Job or undef if the Job can't be found.
See: http://mygengo.com/api/developer-docs/methods/translate-job-id-get/
Retrieves the given Jobs from the API.
The second form allows control over prefetching of comments, revisions and feedback for the Jobs.
Returns a reference to an array of WebService::MyGengo::Job objects on success, undef on failure. (If no results are found but the request succeeded, you'll get a reference to an empty array, as expected.)
See: http://mygengo.com/api/developer-docs/methods/translate-jobs-ids-get/
Searches the API for Jobs according to several optional filters.
Available filters are:
Legal values: unpaid, available, pending, reviewable, approved, rejected , canceled
Returns a reference to an array of WebService::MyGengo::Jobs on success, undef on failure. (If no results are found but the request succeeded, you'll get a reference to an empty array, as expected.)
See: http://mygengo.com/api/developer-docs/methods/translate-jobs-get/
Returns a reference to an array of WebService::MyGengo::Comment objects.
You may find it easier to simply use get_job with the $get_comments flag.
See: http://mygengo.com/api/developer-docs/methods/translate-job-id-comments-get/
Gets a specific revision for the given Job.
Returns an WebService::MyGengo::Revision object.
See http://mygengo.com/api/developer-docs/methods/translate-job-id-revision-rev-id-get/
Gets all revisions for the given job
Revisions are created each time a translator or Senior Translator updates the job.
Returns a reference to an array of WebService::MyGengo::Revision objects.
You may find it easier to simply use get_job with the $get_revisions flag.
See: http://mygengo.com/api/developer-docs/methods/translate-job-id-revisions-get/
Gets feedback for the given Job.
Returns an WebService::MyGengo::Feedback object.
You may find it easier to simply use get_job with the $get_feedback flag.
Note: Even for Jobs without feedback, the API will still return one with a 'rating' of 3.0 and an empty 'for_translator' attribute. This client makes no attempt to handle this situation.
See http://mygengo.com/api/developer-docs/methods/translate-job-id-feedback-get/
Given a single Job, or a reference to a list of Jobs, determines the cost to translate them. The Jobs are not saved to myGengo and the user is not charged for them.
The only Job fields required to determine cost are: lc_src, lc_tgt, tier and body_src. (However, this method makes no effort to ensure you have set them on each Job.)
Returns a reference to an array of Jobs with the 'unit_count' and 'credits' attributes set.
See: http://mygengo.com/api/developer-docs/methods/translate-service-quote-post/
Submits a new translation Job.
Returns the full WebService::MyGengo::Job fetched from the API on success.
Will cowardly refuse to submit a Job without a body_src, lc_src, lc_tgt and tier by throwing an Exception.
See: http://mygengo.com/api/developer-docs/methods/translate-job-post/
Submit multiple Jobs to the API in one call.
If you would like to specify that a single translator work on all of the Jobs, set $as_group to a true value.
Returns a reference to an array of WebService::MyGengo::Job objects from the API on success, undef on failure.
Note: There are some restrictions on what Jobs can be grouped; this client makes no attempt to validate these conditions for you.
See: http://mygengo.com/api/developer-docs/methods/translate-jobs-post/
Adds a comment to the specified Job.
Returns the Job with the `comments` collection refreshed on success, undef on error.
See: http://mygengo.com/api/developer-docs/methods/translate-job-id-comment-post/
Deletes (cancels) a Job.
Returns true on success, false on failure.
Note: You can only cancel a Job if it has not yet been started by a translator.
See: http://mygengo.com/api/developer-docs/methods/translate-job-id-delete/
Deletes (cancels) several Jobs in one API call.
You can only cancel a Job if it has not yet been started by a translator.
Note: This endpoint is documented at the link below, but every calling method I've tried yields a 500 error from the sandbox.
See: http://mygengo.com/api/developer-docs/methods/translate-jobs-delete/
Requests a revision to the given Job.
Instructions for the translator must be provided in $comment.
Returns the Job, updated from the API, on success.
Note: Synonym `revise_job` is provided for convenience, although it does not accurately describe the action performed.
See http://mygengo.com/api/developer-docs/methods/translate-job-id-put/
Approves the most recent translation of the given Job.
A rating is required and must be between 1 (poor) and 5 (excellent.)
Feedback for the translator or for myGengo are optional. If the $public_comments flag is true your feedback may be shared publicly by myGengo.
Rejects the given Job.
A reason for the rejection is required and must be one of: quality, incomplete, other
A comment regarding the rejection and the human-readable text from the image refered to in the Job's `captcha_url` attribute are also required.
You may supply an optional follow-up action for the Job. Legal values are: requeue (re-submit the Job for translation automatically), cancel (cancel the Job outright)
Returns supported translation language pairs, tiers, and credit prices.
$source_language_code is the ISO 2-character code. If provided, only language pairs with that source language will be returned.
Returns a refernece to an array of WebService::MyGengo::LanguagePair objects.
See: http://mygengo.com/api/developer-docs/methods/translate-service-language-pairs-get/
Gets all languages supported by myGengo.
Returns a reference to an array of WebService::MyGengo::Language objects.
See: http://mygengo.com/api/developer-docs/methods/translate-service-languages-get/
* Add caching support * Make fetching of comments/feedback/revisions into global switches * Use concurrent requests to fetch jobs/comments/revisions/feedback/etc. * Support perl < 5.10? Necessary? * I'm not 100% sold on this implementation. I waffle back and forth on whether or not the real API objects should be able to do their own requesting /error handling/etc instead of this client.
Portions of this library are based on the original myGengo.pm library, available here: https://github.com/myGengo/mygengo-perl-new.
That library is Copyright (c) 2011 myGengo, Inc. (http://mygengo.com) and is available under the http://mygengo.com/services/api/dev-docs/mygengo-code-license/ New BSD License.
At the time of this writing the above link is broken. If any portion of this library is in violation of the myGengo license please notify me.
myGengo API documentation: http://mygengo.com/api/developer-docs/
This module on GitHub: https://github.com/nheinric/WebService--MyGengo
Nathaniel Heinrichs
Copyright (c) 2011, Nathaniel Heinrichs <nheinric-at-cpan.org>. All rights reserved.
This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.
To install WebService::MyGengo, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::MyGengo
CPAN shell
perl -MCPAN -e shell install WebService::MyGengo
For more information on module installation, please visit the detailed CPAN module installation guide.