Python wrapper classes around the miiCard API
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
MiiCardConsumers
.gitignore
.travis.yml
CHANGES.txt
LICENSE.txt
MANIFEST
README.md
README.txt
setup.py

README.md

api-wrappers-python

Python wrapper classes around the miiCard API.

This repository houses the source for the latest version of the miiCard Consumers library available on PyPI.

See http://www.miicard.com/developers for more information.

##What is miiCard miiCard lets anybody prove their identity to the same level of traceability as using a passport, driver's licence or photo ID. We then allow external web applications to ask miiCard users to share a portion of their identity information with the application through a web-accessible API.

##What is the library for? miiCard's API is an OAuth-protected web service supporting SOAP, POX and JSON - documentation is available. The library wraps the JSON endpoint of the API, making it easier to make the required OAuth signed requests.

You can obtain a consumer key and secret from miiCard by contacting us on our support form, including the details listed on the developer site.

Pull the library into your own application by downloading the latest released version from PyPI.

##Usage

You'll need to implement your own OAuth exchange with miiCard.com's OAuth endpoint to obtain an access token and secret for a user.

###Accessing the Claims API

Once you've got your consumer key and secret, access token and access token secret you can instantiate an API wrapper:

api = MiiCardOAuthClaimsService("consumer_key", "consumer_secret", "access_token", "access_token_secret")

Then make calls against it simply:

user_profile_response = api.get_claims().data

user_first_name = user_profile_response.data.first_name

###Financial API

Accessing the Financial API is the same, but with a different wrapper type - MiiCardOAuthFinancialService:

api = MiiCardOAuthFinancialService("consumer_key", "consumer_secret", "access_token", "access_token_secret")

###Directory API

Unlike the Claims and Financial APIs, the Directory API is a public lookup service that requires no special OAuth steps to access:

api = MiiCardDirectoryService()

##Test harness

There is a Django test harness that provides a little sample code as well as letting you exercise the APIs and check that OAuth tokens that you've obtained are valid, also available on GitHub along with instructions on how to run and use it.

##Mapping from API data types The following list is provided as a convenient cheat-sheet, and maps the API's methods and data types to their equivalents in the Python wrapper library classes.

###Methods

####Claims API (documentation link)

API methodPython equivalent (given `api` instance of MiiCardOAuthClaimsService)
AssuranceImageapi.assurance_image(type)
GetCardImageapi.get_card_image(snapshot_id, show_email_address, show_phone_number, format)
GetClaimsapi.get_claims()
GetIdentitySnapshotapi.get_identity_snapshot(snapshot_id)
GetIdentitySnapshotPdfapi.get_identity_snapshot_pdf(snapshot_id)
GetIdentitySnapshotDetailsapi.get_identity_snapshot_details()
Or, for a specific snapshot:
api.get_identity_snapshot_details(snapshot_id)
IsSocialAccountAssuredapi.is_social_account_assured(social_account_id, social_account_type)
IsUserAssuredapi.is_user_assured()
IsCreditBureauRefreshInProgressapi.is-credit-bureau-refresh-in-progress()
RefreshCreditBureauDataapi.refresh-credit-bureau-data()

####Financial API (documentation link)

API methodPython equivalent (given `api` instance of `MiiCardOAuthFinancialService`)
IsRefreshInProgressapi.is_refresh_in_progress()
IsRefreshInProgressCreditCardsapi.is_refresh_in_progress_credit_cards()
RefreshFinancialDataapi.refresh_financial_data()
RefreshFinancialDataCreditCardsapi.refresh_financial_data_credit_cards()
GetFinancialTransactionsapi.get_financial_transactions()
GetFinancialTransactionsCreditCardsapi.get_financial_transactions_credit_cards()

####Directory API (documentation link)

Search criterionPython equivalent (given `api` instance of MiiCardDirectoryService)
Anyapi.find_by(criterion, criterion_value, hashed = False)
Usernameapi.find_by_username(username, hashed = False)
Emailapi.find_by_email(email, hashed = False)
Phoneapi.find_by_phone(phone, hashed = False)
Twitterapi.find_by_twitter(twitter_handle_or_url, hashed = False)
Facebookapi.find_by_facebook(facebook_url, hashed = False)
LinkedInapi.find_by_linkedin(linkedin_www_url, hashed = False)
Googleapi.find_by_google(google_handle_or_url, hashed = False)
LiveID/Microsoft IDapi.find_by_microsoft_id(microsoft_id_url, hashed = False)
eBayapi.find_by_ebay(ebay_handle_or_my_ebay_url, hashed = False)
Veritas Vitaeapi.find_by_veritas_vitae(vv_number_or_profile_url, hashed = False)

If you need to hash an identifier you can use the MiiCardDirectoryService.hash_identifier(identifier) static function. This won't normalise the identifier, but will at least lowercase it before hashing - see the Directory API documentation for details on normalisation steps.

###Data types - Claims API

####AuthenticationDetails (documentation link)

API data-type propertyPython equivalent (given `details` instance of `AuthenticationDetails`)
AuthenticationTimeUtcdetails.authentication_time_utc
SecondFactorTypedetails.second_factor_type
SecondFactorProviderdetails.second_factor_provider
Locationsdetails.locations

####AuthenticationTokenType enumeration type (documentation link)

API data-type propertyPython equivalent
NoneAuthenticationTokenType.NONE
SoftAuthenticationTokenType.SOFT
HardAuthenticationTokenType.HARD

####EmailAddress (documentation link)

API data-type propertyPython equivalent (given `email` instance of EmailAddress)
DisplayNameemail.display_name
Addressemail.address
IsPrimaryemail.is_primary
Verifiedemail.verified

####GeographicLocation (documentation link)

API data-type propertyPython equivalent (given `location` instance of `GeographicLocation`)
LocationProviderlocation.location_provider
Latitudelocation.latitude
Longitudelocation.longitude
LatLongAccuracyMetreslocation.lat_long_accuracy_metres
ApproximateAddresslocation.approximate_address

####Identity (documentation link)

API data-type propertyPython equivalent (given `identity` instance of Identity)
Sourceidentity.source
UserIdidentity.user_id
ProfileUrlidentity.profile_url
Verifiedidentity.verified

####IdentitySnapshot (documentation link)

API data-type propertyPython equivalent (given `snapshot` instance of IdentitySnapshot)
Detailssnapshot.details
Snapshotsnapshot.snapshot

####IdentitySnapshotDetails (documentation link)

API data-type propertyPython equivalent (given `snapshot_details` instance of IdentitySnapshotDetails)
SnapshotIdsnapshot_details.snapshot_id
Usernamesnapshot_details.username
TimestampUtcsnapshot_details.timestamp_utc
WasTestUsersnapshot_details.was_test_user

####MiiApiCallStatus enumeration type (documentation link)

API data-type propertyPython equivalent
SuccessMiiApiCallStatus.SUCCESS
FailureMiiApiCallStatus.FAILURE

####MiiApiErrorCode enumeration type (documentation link)

API data-type propertyPython equivalent
SuccessMiiApiCallStatus.SUCCESS
UnknownSearchCriterionMiiApiCallStatus.UNKNOWN_SEARCH_CRITERION
NoMatchesMiiApiCallStatus.NO_MATCHES
AccessRevokedMiiApiCallStatus.ACCESS_REVOKED
UserSubscriptionLapsedMiiApiCallStatus.USER_SUBSCRIPTION_LAPSED
TransactionalSupportDisabledMiiApiCallStatus.TRANSATIONAL_SUPPORT_DISABLED
DevelopmentTransactionalSupportOnlyMiiApiCallStatus.DEVELOPMENT_TRANSACTIONAL_SUPPORT_ONLY
InvalidSnapshotIdMiiApiCallStatus.INVALID_SNAPSHOT_ID
BlacklistedMiiApiCallStatus.BLACKLISTED
ProductDisabledMiiApiCallStatus.PRODUCT_DISABLED
ProductDeletedMiiApiCallStatus.PRODUCT_DELETED
ExceptionMiiApiCallStatus.EXCEPTION

####MiiApiResponse (documentation link)

API data-type propertyPython equivalent (given `response` instance of MiiApiResponse)
Statusresponse.status
ErrorCoderesponse.error_code
ErrorMessageresponse.error_message
Dataresponse.data
IsTestUserresponse.is_test_user

####MiiUserProfile (documentation link)

API data-type propertyPython equivalent (given `profile` instance of MiiUserProfile)
Salutationprofile.salutation
FirstNameprofile.first_name
MiddleNameprofile.middle_name
LastNameprofile.last_name
DateOfBirthprofile.date_of_birth
Ageprofile.age
PreviousFirstNameprofile.previous_first_name
PreviousMiddleNameprofile.previous_middle_name
PreviousLastNameprofile.previous_last_name
LastVerifiedprofile.last_verified
ProfileUrlprofile.profile_url
ProfileShortUrlprofile.profile_short_url
CardImageUrlprofile.card_image_url
EmailAddressesprofile.email_addresses
Identitiesprofile.identities
PhoneNumbersprofile.phone_numbers
PostalAddressesprofile.postal_addresses
WebPropertiesprofile.web_properties
IdentityAssuredprofile.identity_assured
HasPublicProfileprofile.has_public_profile
PublicProfileprofile.public_profile
CreditBureauVerificationprofile.credit-bureau-verification

####PhoneNumber (documentation link)

API data-type propertyPython equivalent (given `phone` instance of PhoneNumber)
DisplayNamephone.display_name
CountryCodephone.country_code
NationalNumberphone.national_number
IsMobilephone.is_mobile
IsPrimaryphone.is_primary
Verifiedphone.verified

####PostalAddress (documentation link)

API data-type propertyPython equivalent (given `address` instance of PostalAddress)
Houseaddress.house
Line1address.line1
Line2address.line2
Cityaddress.city
Regionaddress.region
Codeaddress.code
Countryaddress.country
IsPrimaryaddress.is_primary
Verifiedaddress.verified

####Qualification (documentation link)

API data-type propertyPython equivalent (given `qualification` instance of `Qualification`)
Typequalification.type
Titlequalification.title
DataProviderqualification.data_provider
DataProviderUrlqualification.data_provider_url

####QualificationType enumeration type (documentation link)

API data-type propertyPython equivalent
AcademicQualificationType.ACADEMIC
ProfessionalQualificationType.PROFESSIONAL

####WebProperty (documentation link)

API data-type propertyPython equivalent (given `property` instance of WebProperty)
DisplayNameproperty.display_name
Identifierproperty.identifier
Typeproperty.type
Verifiedproperty.verified

####WebPropertyType enumeration type (documentation link)

API data-type propertyPython equivalent
DomainWebPropertyType.DOMAIN
WebsiteWebPropertyType.WEBSITE

####Model\CreditBureauVerification (documentation link)

API data-type propertyPython equivalent (given `verification` instance of CreditBureauVerification)
Dataverification.data
LastVerifiedverification.last_verified

####Model\CreditBureauRefreshStatus (documentation link)

API data-type propertyPython equivalent (given `status` instance of `CreditBureauRefreshStatus`)
Statestatus.state

###Data types - Financial API

####FinancialAccount (documentation link)

API data-type propertyPython equivalent (given `account` instance of `FinancialAccount`)
AccountNameaccount.account_name
Holderaccount.holder
SortCodeaccount.sort_code
AccountNumberaccount.account_number
Typeaccount.type
FromDateaccount.from_date
LastUpdatedUtcaccount.last_updated_utc
ClosingBalanceaccount.closing_balance
DebitsSumaccount.debits_sum
DebitsCountaccount.debits_count
CreditsSumaccount.credits_sum
CreditsCountaccount.credits_count
CurrencyIsoaccount.currency_iso
Transactionsaccount.transactions

####FinancialCreditCard (documentation link)

API data-type propertyPython equivalent (given `creditCard` instance of `FinancialCreditCard`)
AccountNamecreditCard.account_name
HoldercreditCard.holder
AccountNumbercreditCard.account_number
TypecreditCard.type
FromDatecreditCard.from_date
LastUpdatedUtccreditCard.last_updated_utc
CreditLimitcreditCard.credit_limit
RunningBalancecreditCard.running_balance
DebitsSumcreditCard.debits_sum
DebitsCountcreditCard.debits_count
CreditsSumcreditCard.credits_sum
CreditsCountcreditCard.credits_count
CurrencyIsocreditCard.currency_iso
TransactionscreditCard.transactions

####FinancialProvider (documentation link)

API data-type propertyPython equivalent (given `provider` instance of `FinancialProvider`)
ProviderNameprovider.provider_name
FinancialAccountsprovider.financial_accounts
FinancialCreditCardsprovider.financial_credit_cards

####FinancialRefreshStatus (documentation link)

API data-type propertyPython equivalent (given `status` instance of `FinancialRefreshStatus`)
Statestatus.state

####FinancialTransaction (documentation link)

API data-type propertyPython equivalent (given `transaction` instance of `FinancialTransaction`)
Datetransaction.date
AmountCreditedtransaction.amount_credited
AmountDebitedtransaction.amount_debited
Descriptiontransaction.description
IDtransaction.id

####MiiFinancialData (documentation link)

API data-type propertyPython equivalent (given `data` instance of `MiiFinancialData`)
FinancialProvidersdata.financial_providers

####RefreshState enumeration type (documentation link)

API data-type propertyPython equivalent
UnknownRefreshState.UNKNOWN
DataAvailableRefreshState.DATA_AVAILABLE
InProgressRefreshState.IN_PROGRESS

##Dependencies The library takes a dependency on simplegeo-oauth2, but uses a patched version of it to correct a few issues.

##Contributing

  • Use GitHub issue tracking to report bugs in the library
  • If you're going to submit a patch, please base it off the development branch - the master reflects the latest version published to PyPI but may not necessarily be bleeding-edge

##Licence Copyright (c) 2012, miiCard Limited All rights reserved.

http://opensource.org/licenses/BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of miiCard Limited nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.