> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loqate.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GeoLocation - UK Only
> Find UK addresses within a radius of latitude/longitude coordinates using Ordnance Survey data. Returns address IDs for use with Retrieve API.
The GeoLocation service takes latitude longitude coordinates and returns addresses that are within a specified radius. This must be followed by a Retrieve to obtain a fully formatted address.
This service is only available for UK addresses, using Ordnance Survey data
**This method will consume credit.**
We don't support API connections using HTTP - all calls should use HTTPS.
## OpenAPI
````yaml capture_interactive_geolocation get /Capture/Interactive/GeoLocation/v1.00/json6.ws
openapi: 3.0.0
info:
title: Capture_Interactive_GeoLocation
description: >-
A valuable optional add-on for Capture customers, this Reverse
GeoLocationservice takes a latitude longitude point and returns addresses
that are within a specified radius. This must be followed by a Retrieve to
obtain a fully formatted address.
version: '1'
servers:
- url: https://api.addressy.com
security:
- ApiKeyQuery: []
paths:
/Capture/Interactive/GeoLocation/v1.00/json6.ws:
get:
tags:
- Capture_Interactive_GeoLocation
summary: Capture_Interactive_GeoLocation
description: >-
A valuable optional add-on for Capture customers, this Reverse
GeoLocationservice takes a latitude longitude point and returns
addresses that are within a specified radius. This must be followed by a
Retrieve to obtain a fully formatted address.
operationId: Capture_Interactive_GeoLocation
parameters:
- name: Key
in: query
required: true
description: >-
The key used to authenticate with the service. For example:
'AA11-AA11-AA11-AA11'
schema:
type: string
example: AA11-AA11-AA11-AA11
- name: Latitude
in: query
required: true
description: >-
The latitude of the location you want to return an address for. We
recommend using coordinates with up to six decimal degrees for as
much granularity as possible.
schema:
type: string
example: '52.182728'
- name: Longitude
in: query
required: true
description: >-
The longitude of the location you want to return an address for. We
recommend using coordinates with up to six decimal degrees for as
much granularity as possible.
schema:
type: string
example: '-2.2221217'
- name: Items
in: query
description: >-
The maximum number of items to return. This can be set to a maximum
of 50.
schema:
type: integer
example: '10'
- name: Radius
in: query
description: >-
The maximum radius of the geo-location search in metres. This can be
set to a maximum of 200 metres.
schema:
type: integer
example: '50'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/response'
examples:
Success:
summary: Success
value:
Items:
- Id: RG|131147105004049155081056163145037055217164007108
Type: Address
Text: Loqate
Description: Worcester, WR5 3DA
Latitude: '52.182728'
Longitude: '-2.2221217'
'400':
description: BadRequest
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Country Unavailable:
summary: Country Unavailable
value:
Items:
- Error: '1001'
Description: Country Unavailable
Cause: The country is not available for reverse geocoding.
Resolution: >-
Please ensure that you only attempt to reverse geocode
from supported countries.
Unrecognised Input:
summary: Unrecognised Input
value:
Items:
- Error: '1002'
Description: Unrecognised Input
Cause: The input was not in the expected format.
Resolution: >-
Make sure to pass valid formatted Latitude and
Longitude values.
Request not allowed from this IP:
summary: Request not allowed from this IP
value:
Items:
- Error: '4'
Description: Request not allowed from this IP
Cause: The request was disallowed from the IP address.
Resolution: >-
Check the security settings on the key first. If they
look fine, please contact support as it may be from an
IP address on our blacklist.
Request not allowed from this URL:
summary: Request not allowed from this URL
value:
Items:
- Error: '5'
Description: Request not allowed from this URL
Cause: The request was disallowed from the URL.
Resolution: >-
Check the security settings on the key first. If they
look fine, please contact support as it may be from a
URL on our blacklist.
Web service not available on this key:
summary: Web service not available on this key
value:
Items:
- Error: '6'
Description: Web service not available on this key
Cause: The requested web service is disallowed on this key.
Resolution: >-
Check the security settings on the key first. You can
limit a key to certain web services.
Missing or invalid parameters:
summary: Missing or invalid parameters
value:
Items:
- Error: '18'
Description: Missing or invalid parameters
Cause: >-
A required parameter was not supplied of the value of
a parameter cannnot be converted into the right type.
Resolution: >-
Check the parameters passed and their values against
the specification for this service.
Invalid JSON object:
summary: Invalid JSON object
value:
Items:
- Error: '19'
Description: Invalid JSON object
Cause: The JSON object sent in your request is invalid.
Resolution: >-
Please ensure your JSON object is syntactically
correct and try again.
Endpoint not available:
summary: Endpoint not available
value:
Items:
- Error: '20'
Description: Endpoint not available
Cause: >-
The web service you are calling is not available on
this endpoint
Resolution: >-
Refer to our documentation pages to ensure you are
calling a valid endpoint for the web service you are
requesting.
Sandbox Mode is not available on this endpoint:
summary: Sandbox Mode is not available on this endpoint
value:
Items:
- Error: '21'
Description: Sandbox Mode is not available on this endpoint
Cause: >-
The License key used has Sandbox Mode enabled, but the
testing functionality is not available on this
endpoint.
Resolution: Disable the Sandbox Mode on the License key.
HTTPS requests only:
summary: HTTPS requests only
value:
Items:
- Error: '22'
Description: HTTPS requests only
Cause: >-
As of 3rd September 2018 all new accounts must use
HTTPS.
Resolution: >-
Ensure you consume all of our APIs over HTTPS and not
HTTP.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Unknown key:
summary: Unknown key
value:
Items:
- Error: '2'
Description: Unknown key
Cause: >-
The key you are using to access the service was not
found.
Resolution: >-
Please check that the key is correct. It should be in
the form AA11-AA11-AA11-AA11.
Agreement Not Signed:
summary: Agreement Not Signed
value:
Items:
- Error: '23'
Description: Agreement Not Signed
Cause: >-
There are agreements associated with service which are
not signed.
Resolution: Please go to your account and check your agreements.
Not enough credit for request:
summary: Not enough credit for request
value:
Items:
- Error: '24'
Description: Not enough credit for request
Cause: >-
There is not enough credit on the account to process
the request.
Resolution: Please topup your account with credit.
Unexpected error, please contact the help desk for more information:
summary: >-
Unexpected error, please contact the help desk for more
information
value:
Items:
- Error: '25'
Description: >-
Unexpected error, please contact the help desk for
more information
Cause: ''
Resolution: ''
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Account out of credit:
summary: Account out of credit
value:
Items:
- Error: '3'
Description: Account out of credit
Cause: >-
Your account is either out of credit or has
insufficient credit to service this request.
Resolution: >-
Please check your account balance and top it up if
necessary.
Web service not available on your plan:
summary: Web service not available on your plan
value:
Items:
- Error: '7'
Description: Web service not available on your plan
Cause: >-
The requested web service is not currently available
on your payment plan.
Resolution: >-
Some services are only available in specific regions
due to licensing restrictions. Please contact us for
more information.
Key daily limit exceeded:
summary: Key daily limit exceeded
value:
Items:
- Error: '8'
Description: Key daily limit exceeded
Cause: The daily limit on the key has been exceeded.
Resolution: >-
Alter the daily limit on the key. Check the usage
details first to see if usage is normal.
Your account has been suspended:
summary: Your account has been suspended
value:
Items:
- Error: '9'
Description: Your account has been suspended
Cause: >-
Your account has been suspended. This can be for a
number of reasons including non-payment of an invoice.
Resolution: Please contact us in order to resolve this issue.
Surge protector triggered:
summary: Surge protector triggered
value:
Items:
- Error: '10'
Description: Surge protector triggered
Cause: >-
An unusually large number of requests have been
processed for your account so the surge protector has
been enabled.
Resolution: >-
You can disable the surge protector at any time but
this is only recommended if you are running through a
batch of requests.
No valid license available:
summary: No valid license available
value:
Items:
- Error: '11'
Description: No valid license available
Cause: >-
The request requires a valid license but none were
found.
Resolution: >-
Please check your purchase history. You may be using a
license that is no longer valid or of an incorrect
type.
Management key required:
summary: Management key required
value:
Items:
- Error: '12'
Description: Management key required
Cause: >-
To use this web service you require a management key.
Management can be enabled on any key, but we advise
you to use management keys with care.
Resolution: >-
Sign in to the website and create a new management key
or change an existing key.
Demo limit exceeded:
summary: Demo limit exceeded
value:
Items:
- Error: '13'
Description: Demo limit exceeded
Cause: >-
The daily demonstration limit for this service or
account has been exceeded.
Resolution: >-
The limit will be reset at midnight tonight. If you
would like the limit increased, please contact us.
Free service limit exceeded:
summary: Free service limit exceeded
value:
Items:
- Error: '14'
Description: Free service limit exceeded
Cause: You have used too many free web services.
Resolution: >-
Our web services are designed to operate in stages.
The first is usually a Find service followed by a
Retrieve. If you use too many Finds without the
corresponding number of Retrieves you will receive
this error. For more information, please contact us.
Wrong type of key:
summary: Wrong type of key
value:
Items:
- Error: '15'
Description: Wrong type of key
Cause: >-
The type of key you're using isn't supported by this
web service.
Resolution: >-
This usually happens if you're using a user or server
license with a web service that only supports
transactional keys. Please use another key and try
again.
Key expired:
summary: Key expired
value:
Items:
- Error: '16'
Description: Key expired
Cause: The key you are trying to use has expired.
Resolution: >-
Please check that you are using the right key. A new
one may have been issued if you recently renewed your
key. Contact us if you have any questions.
Individual User exceeded Lookup Limit:
summary: Individual User exceeded Lookup Limit
value:
Items:
- Error: '17'
Description: Individual User exceeded Lookup Limit
Cause: >-
An Individual User has exceeded their daily lookup
limit on the key and that user will be prevented from
using your service until tomorrow (GMT)
Resolution: >-
Check the usage details. If required, increase the
Lookup Limit per Individual User or add the specific
Individual User's IP to the Limiter Exclusions
'500':
description: InternalServerError
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Unknown error:
summary: Unknown error
value:
Items:
- Error: '-1'
Description: Unknown error
Cause: >-
The cause of the error is unknown but details have
been passed to our support staff who will investigate.
Resolution: >-
These problems are typically short lived and are often
resolved by trying again in a few minutes.
components:
schemas:
response:
properties:
Items:
type: array
items:
properties:
Id:
type: string
description: An address id to pass to the Retrieve endpoint.
Type:
type: string
description: This will always be Address.
Text:
type: string
description: >-
The highest level address details for the returned address;
usually either an organisation name/description if available
(i.e. the contents of the Company field), otherwise the first
line of an address (i.e. Line1).
Description:
type: string
description: >-
Additional details for the returned address, comprised of the
contents of the City and Postcode fields.
Latitude:
type: string
description: The latitude of the returned address.
Longitude:
type: string
description: The longitude of the returned address.
error:
properties:
Items:
type: array
items:
properties:
Error:
type: string
description: The id of the error returned
Description:
type: string
description: A description of the error
Cause:
type: string
description: The cause of the error
Resolution:
type: string
description: Actions to resolve the error
securitySchemes:
ApiKeyQuery:
type: apiKey
name: Key
in: query
````