Metadata-Version: 2.0
Name: postcodeinfo
Version: 0.0.2
Summary: API client for https://github.com/ministryofjustice/postcodeinfo
Home-page: https://github.com/ministryofjustice/postcodeinfo-client-python
Author: Andy Driver
Author-email: andy.driver@digital.justice.gov.uk
License: LICENSE
Keywords: python,ministryofjustice,govuk
Platform: any
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: requests (>=2.7,<3)

PostcodeInfo Client
===================

.. image:: https://travis-ci.org/ministryofjustice/postcodeinfo-client-python.svg
  :alt: Travis CI build status
  :target: https://travis-ci.org/ministryofjustice/postcodeinfo-client-python

Python package providing an API client for https://github.com/ministryofjustice/postcodeinfo


Installation
------------

.. code-block:: bash

    pip install postcodeinfo


Usage
-----

Authentication
~~~~~~~~~~~~~~

You will need an *authentication token* (auth token). If you're using MOJ DS's
Postcode Info server, you can get a token by emailing
platforms@digital.justice.gov.uk with a brief summary of:

* who you are
* what project you're going to be using it on
* roughly how many lookups you expect to do per day

If you're running your own server, see
https://github.com/ministryofjustice/postcodeinfo#auth_tokens for instructions
on how to create a token.

Quick Start
~~~~~~~~~~~

In your code:

.. code-block:: python

    >>> import postcodeinfo

    >>> # create a client
    >>> client = postcodeinfo.Client("YOUR-ACCESS-TOKEN")

    >>> # lookup a postcode
    >>> postcode = client.lookup_postcode("SW1A 1AA")

    >>> # postcode details
    >>> postcode.valid
    True

    >>> postcode.latitude
    51.50100893654096

    >>> postcode.longitude
    -0.141587558526369

    >>> postcode.local_authority
    {
        'gss_code': 'E09000033',
        'name': 'Westminster'
    }

    >>> postcode.addresses
    [
        {
            "uprn": "10033544614",
            "organisation_name": "BUCKINGHAM PALACE",
            "department_name": "",
            "po_box_number": "",
            "building_name": "",
            "sub_building_name": "",
            "building_number": None,
            "thoroughfare_name": "",
            "dependent_thoroughfare_name": "",
            "dependent_locality": "",
            "double_dependent_locality": "",
            "post_town": "LONDON",
            "postcode": "SW1A 1AA",
            "postcode_type": "L",
            "formatted_address": "Buckingham Palace\nLondon\nSW1A 1AA",
            "point": {
                "type": "Point",
                "coordinates": [
                    -0.141587558526369,
                    51.50100893654096
                ]
            }
        }
    ]


Configuration
-------------

Apart from the auth token, there is only one other parameter the API client
needs - ``api_url``.

Explicit ``api_url``
~~~~~~~~~~~~~~~~~~~~

You can set the api_url explicitly by passing it to the ``Client`` constructor

.. code-block:: python

    # create a client
    client = postcodeinfo.Client("YOUR-API-TOKEN", api_url="https://some.dom.ain")

or by setting it on an existing client, like this

.. code-block:: python

    client = postcodeinfo.Client("YOUR-API-TOKEN")
    client.api_url = "https://some.dom.ain"

Implicit ``api_url``
~~~~~~~~~~~~~~~~~~~~

If you don't pass an ``api_url`` to the constructor, it will attempt to infer
one from the environment. The client has a built-in mapping of environment names
to URLs.

.. code-block:: python

    >>> postcodeinfo.Client.api_urls
    {
        'development': 'http://localhost:8000',
        'test': 'http://localhost:8000',
        'staging': 'https://postcodeinfo.dsd.io',
        'production': 'https://postcodeinfo.service.gov.uk'
    }

It will use the following rules to infer the URL:

1. If you pass an ``env`` parameter to the constructor (eg:
   ``client = postcodeinfo.Client("YOUR-API-TOKEN", env="staging")``), it will
   use that as a reference into the ``api_urls`` mapping.
2. If you have ``DJANGO_SETTINGS_MODULE`` set in your environment, it will try
   to find the following settings in that module::

    POSTCODEINFO_API_URL
    POSTCODEINFO_API_TOKEN
    POSTCODEINFO_API_TIMEOUT

3. Otherwise it will default to ``development``


Support
-------

This source code is provided as-is, with no incident response or support levels.
Please log all questions, issues, and feature requests in the Github issue
tracker for this repo, and we'll take a look as soon as we can. If you're
reporting a bug, then it really helps if you can provide the smallest possible
bit of code that reproduces the issue. A failing test is even better!


Contributing
------------

* Check out the latest master to make sure the feature hasn't been implemented
  or the bug hasn't been fixed
* Check the issue tracker to make sure someone hasn't already requested
  and/or contributed the feature
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure your changes are covered by unit tests, so that we don't break it
  unintentionally in the future.
* Please don't mess with setup.py, version or history.


Copyright
---------

Copyright |copy| 2015 HM Government (Ministry of Justice Digital Services). See
LICENSE for further details.

.. |copy| unicode:: 0xA9 .. copyright symbol


