> ## 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.
# Map Tile API
> Generate signed URLs for map tiles and basemap data. Use with MapLibre or Leaflet to render interactive maps showing customer locations and stores.
Please note that we are unable to serve map data for China.
The Map Tile API takes an input of your Loqate key and returns a Signed URL, which is valid for one hour and can be used to provide secure access our tile server.
Whilst the Signed URL is active you can make as many requests using that URL as needed.
Our tile server provides access to basemap data, tiles and styling for a map. This can then be used with a map rendering library, such as [MapLibre](https://github.com/maplibre/maplibre-gl-js)
or [Leaflet](https://leafletjs.com/examples/quick-start/), to add an interactive map to your application.
Other functionality required for your map, such as pins for locations, can then be added afterwards via the map renderer.
### Mapping Concepts
There are several key concepts that are important to understand when implementing a map using this API:
* **Signed URL:** a secure URL generated for a specific session within a limited time period, with limited permissions. This contains authentication information within the query, thus reducing the time required to authenticate and reducing overall response times. You will receive two signed URLs, one for vector based tiles and another for raster based tiles
* **Basemap data:** basemaps form the foundation for your map, providing geographic context stored as tile layers. These layers include the context required to display useful information such as the names of streets, buildings and land categorisation
* **Vector tiles:** a format of tile that stores map data using vector shapes. As these are composed dynamically, they can be easily styled and smoothly zoom in and out as a user is navigating. These are generally faster to load than Raster tiles, but can be more demanding on the end user's hardware
* **Raster tiles:** a format of tile that stores map data using grids of pixels, commonly as images. These tiles can be slower to load than vector tiles, but are generally less demanding on the end user's hardware
* **Map Style:** a Map style is a JSON document that defines how the map will appear when rendered
* **Map renderer:** library required to render a map within an application. Once you have defined your data source as the signed URL you receive from this API, the map rendering library will pull data from Loqate at run time, rendering the map data for you. Commonly used open source libraries for this include MapLibre, Leaflet and Amplify
### Application flow using a map renderer
Signed URLs can be used to request individual map tiles if required, however for more complex applications you're likely to use a map renderer.
The following diagram represents how an application could be designed to work with our API and a map renderer:
Here are the steps this flow takes:
1. Make a request to [https://api.addressy.com/LocationServices/Mapping/GetUrl/v1.00/json4.ws?key=\{\{license\_key}}](https://api.addressy.com/LocationServices/Mapping/GetUrl/v1.00/json4.ws?key=\{\{license_key}}) (adding in your own API key)
2. Receive multiple Signed URLs in the response (one for Raster tiles and one for Vector tiles)
3. Choose whether you want to use Raster tiles or Vector tiles, and pass the appropriate Signed URL to the map renderer
4. The map renderer will request basemap data from Loqate as needed (for instance this could be when a user scrolls on your map and the renderer interprets which tiles will be needed next)
5. Loqate will return the appropriate map data
6. The map renderer will then use this data to render the map on the screen of your browser
**This method will consume credit each time a signed URL is generated.**
You must ensure attribution is visible when rendering a map as part of your application. Loqate uses map styling from [OpenMapTiles](https://osmfoundation.org/wiki/Licence/Attribution_Guidelines)
and open data from [OpenStreetMaps](https://www.openstreetmap.org/copyright). Attribution is provided by default as part of the map style configuration,
however if you choose to create your own map styling you must still ensure that this attribution is visible. For further information on copyright notices please
see the [Loqate Terms and Conditions](https://www.gbgplc.com/en/legal-and-regulatory/products/loqate-storefinder/legal-notices-loqate-storefinder/).
## OpenAPI
````yaml mapping_get_url post /LocationServices/Mapping/GetUrl/v1.00/json6.ws
openapi: 3.0.0
info:
title: LocationServices_Mapping_GetUrl
description: ''
version: '1'
servers:
- url: https://api.addressy.com
security:
- ApiKeyQuery: []
paths:
/LocationServices/Mapping/GetUrl/v1.00/json6.ws:
post:
tags:
- LocationServices_Mapping_GetUrl
summary: LocationServices_Mapping_GetUrl
operationId: LocationServices_Mapping_GetUrl
requestBody:
x-name: body
content:
application/json:
schema:
title: TileUrlGeneratorRequest
allOf:
- $ref: '#/components/schemas/RequestItem'
- type: object
additionalProperties: false
responses:
'200':
description: Success
content:
application/json:
schema:
title: TileUrlGeneratorResponse
type: object
additionalProperties: false
properties:
VectorStyleUrl:
type: string
description: >-
Signed URL to use when wanting to render Vector tiles,
valid for one hour after creation. This URL contains all
the information required by a map renderer to draw the
layers of data for the final map. Vector tiles offer more
flexibility with styling and improved performance when
navigating the map but they can be more demanding on end
user hardware.
RasterStyleUrl:
type: string
description: >-
Signed URL to use when wanting to render Raster tiles,
valid for one hour after creation. This will give you no
flexibility over styling options and can be slower to load
but is generally less demanding on end user hardware.
GeneratedOnUtc:
type: string
description: >-
UTC Timestamp representing when the URLs were signed and
generated.
format: date-time
'400':
description: BadRequest
content:
application/json:
schema:
title: ErrorResponseSelfContained
type: object
additionalProperties: false
properties:
Number:
type: integer
format: int32
Description:
type: string
Cause:
type: string
Resolution:
type: string
examples:
Request not allowed from this IP:
summary: Request not allowed from this IP
value:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
title: ErrorResponseSelfContained
type: object
additionalProperties: false
properties:
Number:
type: integer
format: int32
Description:
type: string
Cause:
type: string
Resolution:
type: string
examples:
Unknown key:
summary: Unknown key
value:
Number: 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:
Number: 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:
Number: 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:
Number: 25
Description: >-
Unexpected error, please contact the help desk for more
information
Cause: ''
Resolution: ''
'403':
description: Forbidden
content:
application/json:
schema:
title: ErrorResponseSelfContained
type: object
additionalProperties: false
properties:
Number:
type: integer
format: int32
Description:
type: string
Cause:
type: string
Resolution:
type: string
examples:
Account out of credit:
summary: Account out of credit
value:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
Number: 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:
title: ErrorResponseSelfContained
type: object
additionalProperties: false
properties:
Number:
type: integer
format: int32
Description:
type: string
Cause:
type: string
Resolution:
type: string
examples:
Unknown error:
summary: Unknown error
value:
Number: -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.
InternalServerError:
summary: InternalServerError
value:
Number: 1000
Description: InternalServerError
Cause: Something unexpected has happened on the server
Resolution: >-
Please contact support and quote the error number and this
api endpoint
'1001: InternalServerError':
summary: InternalServerError
value:
Number: 1001
Description: InternalServerError
Cause: Something unexpected has happened on the server
Resolution: >-
Please contact support and quote the error number and this
api endpoint
'1002: InternalServerError':
summary: InternalServerError
value:
Number: 1002
Description: InternalServerError
Cause: Something unexpected has happened on the server
Resolution: >-
Please contact support and quote the error number and this
api endpoint
components:
schemas:
RequestItem:
type: object
additionalProperties: false
properties:
Key:
type: string
securitySchemes:
ApiKeyQuery:
type: apiKey
name: Key
in: query
````