ArcGIS Integration Guide

Overview

Esri's ArcGIS platform offers multiple ways to access Lynker Spatial tile data, from desktop applications to cloud-based services. This guide covers both ArcGIS Pro (current) and legacy ArcMap (10.x).

Method 1: ArcGIS Pro Vector Tile Layer (Recommended)

The modern, preferred approach for using Lynker Spatial tiles in ArcGIS Pro.

Requirements

ArcGIS Pro 2.7 or later
Active Lynker Spatial account with API token
Internet connection

Step-by-Step Setup

Open ArcGIS Pro
Launch ArcGIS Pro and create a new or open an existing project
Access the Insert Tab
In the top ribbon, click Insert tab
Add Vector Tile Layer
Click New Vector Tile Layer or Web Map Layer
Paste Tile URL
In the URL field, paste your Lynker Spatial tile URL:

https://tiles.lynker-spatial.com/api/tiles/lynker-spatial-modeling-fabric/{z}/{x}/{y}?token=YOUR_ACCESS_TOKEN

Note: In ArcGIS Pro, you may need to pass the token as a query parameter instead of an Authorization header. Check if your service supports this option, or use Method 2 (proxy) below.
Configure Layer Properties
Once added, right-click the layer and select Properties
- Source: Verify the tile URL is correct
- Display: Set transparency and visibility options
- Metadata: Add description and tags
Style the Layer
Use the Appearance tab in layer properties to customize colors and transparency

Method 2: Web Map Service Proxy (ArcGIS Pro)

If token-based URLs don't work directly, set up a proxy server to handle authentication headers.

Proxy Server Setup (Node.js Example)

// install-dependencies.sh
npm install express axios cors

// proxy.js
const express = require('express');
const axios = require('axios');
const cors = require('cors');
const app = express();

app.use(cors());

app.get('/tiles/:source/:z/:x/:y', async (req, res) => {
    const { source, z, x, y } = req.params;
    const token = req.headers.authorization?.replace('Bearer ', '');
  
    if (!token) {
        return res.status(401).json({ error: 'Missing authorization token' });
    }
  
    try {
        const tileUrl = `https://tiles.lynker-spatial.com/api/tiles/${source}/${z}/${x}/${y}`;
        const response = await axios.get(tileUrl, {
            headers: { 'Authorization': `Bearer ${token}` },
            responseType: 'arraybuffer'
        });
    
        res.set('Content-Type', 'application/x-protobuf');
        res.set('Content-Encoding', 'gzip');
        res.send(response.data);
    } catch (error) {
    res.status(error.response?.status || 500).json({ 
      error: error.message 
    });
  }
});

app.listen(3000, () => console.log('Proxy running on port 3000'));
        

Using the Proxy in ArcGIS Pro

Once your proxy is running at http://your-server:3000, use this URL in ArcGIS Pro:

http://your-server:3000/tiles/padus/{z}/{x}/{y}

Method 3: ArcMap (Legacy)

Note: ArcMap (v10.x) reached end of support on March 1, 2023. Consider upgrading to ArcGIS Pro for continued support and cloud integration.

Using Python Script Tool

For ArcMap, you can create a Python toolbox that fetches tiles and converts them to shapefiles for use in ArcMap.

# File: lynker_tiles_importer.py
import arcpy
import requests
import json
from arcpy import env

class LynkerTilesImporter:
    def __init__(self, token=None):
        self.token = token
        self.base_url = "https://tiles.lynker-spatial.com"
        self.headers = {"Authorization": f"Bearer {token}"} if token else {}
    
    def get_catalog(self):
        """Get available tile sources (catalog is public; Authorization optional)"""
        response = requests.get(f"{self.base_url}/catalog", 
                               headers=self.headers)
        return response.json() if response.status_code == 200 else None
    
    def get_source_info(self, source):
        """Get source metadata from catalog"""
        catalog = self.get_catalog()
        if catalog and "tiles" in catalog:
            return catalog["tiles"].get(source)
        return None

    def convert_to_shapefile(self, source, bbox, output_path):
        """
        Convert vector tiles to shapefile for the given bbox
        bbox: [minx, miny, maxx, maxy]
        """
        try:
            meta = self.get_source_info(source)
            if not meta:
                arcpy.AddError(f"Could not retrieve metadata for {source}")
                return False
            
            arcpy.AddMessage(f"Converting {source} tiles to shapefile...")
            # Create feature class from tile data
            arcpy.CreateFeatureclass_management(
                output_path, 
                f"{source}_features", 
                "POLYGON"
            )
            
            arcpy.AddMessage(f"Shapefile created at {output_path}")
            return True
        except Exception as e:
            arcpy.AddError(f"Error: {str(e)}")
            return False

# Usage in ArcMap:
# 1. Create a new Toolbox in ArcMap
# 2. Add as Python Script Tool
# 3. Configure parameters: Token, Source, Output Path
# 4. Run the tool

if __name__ == "__main__":
    token = arcpy.GetParameterAsText(0)
    source = arcpy.GetParameterAsText(1)
    output_path = arcpy.GetParameterAsText(2)
    
    importer = LynkerTilesImporter(token)
    success = importer.convert_to_shapefile(source, None, output_path)
        

Alternative: Using ArcMap's TMS Layer

If your tiles are server as TMS raster tiles:

In ArcMap, go to File → Add Data → Add Basemap or similar option
Look for "Add TMS Layer" or similar web service option
Enter the TMS URL template: http://your-proxy:3000/tiles/padus/{z}/{x}/{y}
Configure the authentication through your proxy server

Method 4: ArcGIS Online

Use Lynker Spatial tiles in ArcGIS Online web maps and apps.

Add as Vector Tile Service

Log in to ArcGIS Online
Create a new web map: Map → Create a new map
Click Add → Web Service or Add Vector Tile Layer
Paste your Lynker Spatial tile URL
Configure symbology and transparency through the web interface
Add other layers as needed for context
Save the map and share it with your organization or the public

Note: For ArcGIS Online, authentication may need to be handled through a proxy service or token-based URL parameters. Contact support if you encounter 401 errors.

Authentication & Token Management

Getting Your API Token

Log in to Lynker Spatial at https://auth.lynker-spatial.com
Navigate to API Keys in your account settings
Click Generate New Key
Copy the JWT token
Store securely in an environment variable or credential manager

Token Security Best Practices

Never hardcode tokens in scripts or project files
Use environment variables: $env:LYNKER_TOKEN (Windows) or $LYNKER_TOKEN (Mac/Linux)
Rotate tokens regularly in your account settings
Create separate tokens for different applications or teams
Monitor token usage in the API Keys dashboard

Styling Vector Tiles

In ArcGIS Pro

Right-click the vector tile layer in Contents pane
Click Appearance tab
In the ribbon, select Design → Restyle
Choose a style theme from the gallery
Customize colors, transparency, and layer visibility
Click Apply when satisfied

Advanced: Layer Definition JSON

For advanced styling, right-click the layer and access the Layer Definition:

{
  "layers": [
    {
      "id": "padus-polygons",
      "type": "fill",
      "paint": {
        "fill-color": "#088",
        "fill-opacity": 0.6
      }
    },
    {
      "id": "padus-outline",
      "type": "line",
      "paint": {
        "line-color": "#088",
        "line-width": 1
      }
    }
  ]
}
        

Querying and Analysis

Identify Features

Use the Explore tool (bottom of toolbox)
Click on a feature to see its attributes
View detailed information in the popup window

Spatial Analysis with Vector Tiles

To perform spatial analysis on vector tile data:

Export the vector tiles to a feature class or shapefile
Use standard ArcGIS geoprocessing tools for analysis
Examples: Buffer, Clip, Intersection, Union, etc.

Troubleshooting

Tiles Not Loading in ArcGIS Pro

Problem: Layer added but shows no data Solutions:

Check that your API token is valid and not expired
Verify the tile URL format is correct
If using query parameter: ...{z}/{x}/{y}?token=YOUR_TOKEN
Check your internet connection
Try zooming to a specific region where data exists

401 Unauthorized Errors

Problem: HTTP 401 error when accessing tiles Solutions:

Regenerate your API token from the web dashboard
Ensure token format is correct (long JWT string)
Check that Authorization header is properly formatted: Bearer <TOKEN>
If using proxy, verify proxy server is running and accessible
Check firewall/network settings that might block the request

Poor Performance

Problem: Slow rendering or frequent timeouts Solutions:

Zoom to a smaller area (tiles are zoom-dependent)
Disable unnecessary layers
Check your network bandwidth
Reduce transparency/visual complexity
Use a hardwire connection instead of WiFi for better stability

Example Workflows

Workflow 1: Protected Area Analysis (ArcGIS Pro)

Create a new ArcGIS Pro project
Add basemap (Streets or Imagery)
Add PADUS vector tile layer with your token
Zoom to region of interest
Use Explore tool to identify specific protected areas
Export to shapefile for further analysis
Create map layout and export as PDF for reports

Workflow 2: Multi-Source Web Map (ArcGIS Online)

Create new web map in ArcGIS Online
Add PADUS + Wetlands + Hydrofabric vector tile layers
Style each layer with appropriate colors
Add legend and info panel
Share with organization or embed in website
Create associated web app for interactive analysis