Get Started

The Bettermile product suite offers unified authentication. Whether you need geolocation services or route optimization algorithms, you can seamlessly access them once your client is authenticated and the correct scopes are assigned.

Machine to Machine (M2M) Communcation

For secure, automated interactions between devices or systems, Bettermile uses machine-to-machine (M2M) authentication. This process verifies the identity of each communicating party, eliminating the need for human involvement.

Step 1: Credentials

To authenticate your machine, you must first create it. Please follow these steps to get started:

1. Log in to Bettermile Backoffice.
2. Navigate to Tenant Machine Management.
3. Create a New Tenant Machine.
4. Save Your Credentials

Step 2: Authentication

Now that the Tenant Machine has been created, you can authenticate it using the id and secret returned during the creation process.

curl -i -X POST \
  -u <username>:<password> \
  https://auth.bettermile.com/api/v1/machines/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials

{
  "access_token": "eyJhbGciOiJIUz...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

For detailed instructions on using the Authentication API, please refer to the Authentication API Documentation.

Step 3: Authorization - Product Access

Once authenticated, you can start making requests to Bettermile's Product Suite.

curl -i -X POST \
  https://places.bettermile.com/api/v2/geocode \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": {
      "street": "Otto-Weidt-Platz 8",
      "countryCode": "DE"
    }
  }'

{
  "rawAddressId": 12345,
  "timeframe": {
    "earliest": "09:00:00",
    "latest": "10:00:00",
    "zoneId": "Europe/Berlin"
  },
  "coordinates": {
    "lat": 52.53294,
    "lng": 13.36718
  },
  "entranceCoordinates": {
    "points": [ … ]
  },
  "parkingCoordinates": {
    "points": []
  },
  "formatted": "Otto-Weidt-Platz 8, 10557 Berlin, Germany",
  "street": "Otto-Weidt-Platz",
  "number": 8,
  "postalCode": 10557,
  "locality": "Berlin",
  "subLocality": "Mitte",
  "countryCode": "DE",
  "accuracy": {
    "houseNumberFallback": null,
    "houseNumberChanged": false,
    "postalCodeChanged": false,
    "postalCodeChangeValid": null,
    "score": 100,
    "level": "ADDRESS_POINT"
  },
  "zoneId": "Europe/Berlin"
}

Best Practices

To ensure smooth, secure, and efficient usage of our APIs, follow these best practices:

• Rate Limiting: Stay within the rate limit of X requests per minute and quota. Exceeding this limit may result in throttling or temporary access denial.
• Error Handling: Always check the response status codes. If an error occurs, handle it gracefully with appropriate fallback mechanisms.
• Secure Your API Key: Never expose your API key in public repositories, front-end code, or in any client-side environment.