Documentation

Learn how to integrate Addressd's delivery optimization and natural language directions into your applications.

Delivery API

Optimize your delivery operations with our API endpoints.

Authentication

Include your API token in the Authorization header of your requests:

Authorization: Bearer your_api_token_here

Get Delivery Directions

Generate natural language directions for a specific address:

curl -X POST https://api.addressd.app/v1/address/validate \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St, City, Country"
  }'

Response Format

{
  "formattedAddress": "123 Main St, City, Country",
  "summary": "The entrance is on the north side of Main St...",
  "uploadLink": "/upload/abc123",
  "addressId": "abc123"
}

Error Handling

All endpoints return consistent error responses:

Error Response Format

{
  "error": "Error message here",
  "details": "Additional error details (in development)"
}

Common Error Codes

400 - Invalid request (missing fields, invalid format)
401 - Unauthorized (missing or invalid API key)
405 - Method not allowed
500 - Internal server error

CORS Support

All API endpoints support CORS and handle preflight requests automatically. The following headers are included in responses:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

Rate Limiting

Plan	Rate Limit	Burst Limit
API Basic	1,000 requests/day	50 requests/minute
API Pro	10,000 requests/day	100 requests/minute
Enterprise	Custom	Custom

Contribute Directions

Add or update directions for an address:

curl -X POST https://api.addressd.app/v1/address/contribute \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St, City, Country",
    "description": "The building has a distinctive blue awning..."
  }'

Response Format

{
  "addressId": "abc123",
  "isNewAddress": false,
  "pointsEarned": 0.0125
}

Points System

New location description: 0.05 credits
Improving existing description: 0.0125 credits

Embed Integration

Add natural language directions to your website with our embed widget.

Quick Start

Add this code to your website where you want the directions widget to appear:

<!-- Add the Addressd script -->
<script src="https://addressd.app/embed.js"></script>

<!-- Add the directions widget -->
<div id="addressd-directions"></div>

<!-- Initialize with your configuration -->
<script>
  new AddressdDirections({
    element: '#addressd-directions',
    apiKey: 'your_api_key',
    address: '123 Main St, City',
    theme: 'light',  // or 'dark'
    language: 'en'   // default: 'en'
  });
</script>

Configuration Options

{
  // Required
  element: '#addressd-directions',  // CSS selector for the container
  apiKey: 'your_api_key',          // Your API key
  address: '123 Main St, City',    // Address to show directions for

  // Optional
  theme: 'light',                  // 'light' or 'dark'
  language: 'en',                  // Language code
  width: '100%',                   // Container width
  height: 'auto',                  // Container height
  showMap: true,                   // Show map preview
  mapType: 'roadmap'              // 'roadmap' or 'satellite'
}

Events

The widget emits events you can listen to:

loaded - When the directions are loaded
error - When an error occurs
feedback - When user provides feedback

const widget = new AddressdDirections({...});

widget.on('loaded', (data) => {
  console.log('Directions loaded:', data);
});

widget.on('error', (error) => {
  console.error('Error:', error);
});

widget.on('feedback', (feedback) => {
  console.log('User feedback:', feedback);
});

Live Example

Delivery Instructions

The entrance is on the north side of Main Street. Look for the blue awning next to the coffee shop. The delivery entrance is through the side alley.

123 Main Street, City

Contribute API

Help improve our database by contributing detailed location descriptions. Earn credits for your contributions.

Submit a Contribution

curl -X POST https://api.addressd.app/v1/contribute \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St, City, Country",
    "description": "The building has a distinctive blue awning...",
    "landmarks": ["Blue awning", "Corner cafe"],
    "accessPoints": ["Main entrance on Main St", "Service entrance in alley"]
  }'

Contribution Credits

New location description: 0.05 credits
Improving existing description: 0.0125 credits
Credits can be used to reduce API usage costs

Rate Limits

Plan	Rate Limit	Burst Limit
API Basic	1,000 requests/day	50 requests/minute
API Pro	10,000 requests/day	100 requests/minute
Enterprise	Custom	Custom