= comcetera

A simple wrapper for the NumberPortabilityLookup service of Comcetera. Give them a msisdn and they (usually) give you an operator code. Compile your own list of relevant codes based on wikipedia.

I'm scratching my own itch here, so I'm only adding what I use. Feedback and patches are welcome.

For more info about the service, take a look at: http://numberportabilitylookup.com/

== Example

The usual way you'd do a lookup

  Comcetera.username = "meeeeee"
  Comcetera.password = "verysecret"
  comcetera = Comcetera.detect(31612345678)
  comcetera.operator_code # => "20415"
  comcetera.msisdn        # => "31612345678"

When the lookup does not work due to a timeout

  Comcetera.detect(31612345678) # => nil

This means that the amount of retries specified as Comcetera.retries have all timed out after Comcetera.timeout seconds. You can retry at a later time or do something else. This is great if, as is my use case, the lookup is used as a type of pre-selection for numbers.

The API can return a couple of errors. In this case, there is no operator code, but an error code and the full response as debug info.

  comcetera = Comcetera.detect(31612345678)
  comcetera.operator_code # => nil
  comcetera.error_code    # => "ERR29"
  comcetera.error_message # => "Absent subscriber"
  comcetera.debug         # => "QUERYOK\n31612345678 ERR29\nENDBATCH"

== Operator codes

Check the wikipedia page for Mobile Network Codes (http://en.wikipedia.org/wiki/Mobile_Network_Code) for a list of codes that you can expect.

Example: Wikipedia mentions T-Mobile in the Netherlands as: MCC 204, MNC 16. Comcetera would return this as code 20416. This logic seems consistent across countries.

== Note on Patches/Pull Requests

* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

== Contributors

* Wes 'Narnach' Oldenbeuving
* Gerard 'smeevil' de Brieder

== Copyright

Copyright (c) 2010 Wes Oldenbeuving. See LICENSE for details.