Geolocation Service
===================


The Geolocation Service provides an endpoint for retrieving the latitude and longitude of a given address.

.. contents:: Topics

Endpoints
---------

Coordinates by Address
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. http:post:: geolocation/coordinatesByAddress.json

   This endpoint takes in an address, and returns the latitude and longitude associated with that address. If the address provided does not exactly match up with a real address (for example, it's a section of street with no building on it) the endpoint will still return successfully with the exactMatch flag set to false. If the address cannot be found, the endpoint will return a failure response.
   
   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`

   :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. 
   :jsonparam String address: *(required)*  The street number and street name of the address. Example: 123 Main Street
   :jsonparam String city: *(required)* The city of the address. Example: Boston
   :jsonparam String stateProvince: *(required)* The two letter state or province code of the address. Full names are also supported. Example: MA or Massachusetts
   :jsonparam String postalCode: *(optional)* The US ZIP code or Canadian Province Code of the address. Example: 02111
   :jsonparam String postalCode: *(optional)* The two letter country code of the address. Full country names are also supported. Examples: US, USA, or United States of America

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam BigDecimal lat: *(required)* The latitude (in degrees) of the address. Example: 42.384620
   :jsonparam BigDecimal lon: *(required)* The longitude (in degrees) of the address. Example: -71.205700
   :jsonparam Boolean exactMatch: *(required)* Indicates whether the coordinates are an exact match to the address, or if they are an approximation. True for an exact match.
.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure`` or ``inputFailure``
   :jsonparam String code: *(required)* A static code unique for each type of error.
   :jsonparam String message: *(required)* Further explanation of the error code, which is subject to change in different versions of the endpoint.