Cartes.io Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with Cartes.io's API involves a sequence of steps to ensure proper setup and functionality. This guide outlines the process from account creation to executing your first API call. Cartes.io provides geocoding, reverse geocoding, and search functionalities, which rely on an API key for authentication. The service is structured to be compatible with standard REST conventions, supporting common HTTP methods and JSON responses. For detailed technical specifications, refer to the Cartes.io API reference.

The initial setup typically includes:

1. Account Creation: Registering on the Cartes.io platform to establish a user profile.
2. API Key Retrieval: Locating and copying the unique API key from your account dashboard. This key is essential for authenticating all requests.
3. First API Call: Constructing and sending a basic request to a Cartes.io endpoint, such as the geocoding API, to verify connectivity and authentication.
4. Response Handling: Processing the JSON response returned by the API to confirm successful data retrieval.

Cartes.io offers a free tier that includes 5,000 requests per month, which can be used for development and testing purposes without immediate cost. This tier allows developers to explore the API's capabilities and integrate it into applications before considering paid plans, which begin at €10 per month for 50,000 requests.

Create an account and get keys

To access Cartes.io's API, you must first create an account and obtain an API key. This key serves as a credential to authenticate your requests against the Cartes.io API infrastructure, similar to how Stripe API keys or PayPal API credentials function for their respective services.

1. Navigate to the Cartes.io Homepage: Open your web browser and go to the Cartes.io website.
2. Initiate Sign-Up: Look for a 'Sign Up' or 'Get Started' button, usually located in the top right corner or prominent on the main page. Click this button to begin the registration process.
3. Provide Registration Details: You will be prompted to enter an email address and create a password. Follow any additional instructions, such as agreeing to terms of service or privacy policies. Some services may offer single sign-on (SSO) options using existing accounts like Google or GitHub.
4. Verify Email (if required): Cartes.io may send a verification email to the address you provided. Check your inbox and spam folder for this email and click the verification link to activate your account.
5. Access Your Dashboard: Once registered and logged in, you will be directed to your Cartes.io account dashboard.
6. Locate Your API Key: Within the dashboard, there will typically be a section labeled 'API Keys', 'Credentials', or 'Settings'. Navigate to this section. Your unique API key will be displayed here. It's usually a long string of alphanumeric characters.
7. Copy Your API Key: Copy the API key to a secure location. Treat your API key as sensitive information, similar to a password, to prevent unauthorized access to your account and usage limits. Do not hardcode it directly into client-side code that could be publicly exposed.

The API key is typically passed as a query parameter in your API requests. For example, a request might look like https://api.cartes.io/geocode?q=address&key=YOUR_API_KEY. Always consult the Cartes.io API documentation for the precise method of passing the API key, as some APIs might prefer header-based authentication.

Your first request

After obtaining your API key, you can make your first request to test the Cartes.io API. This example uses the geocoding endpoint, which converts a human-readable address into geographical coordinates (latitude and longitude).

The Cartes.io geocoding API endpoint is structured as a RESTful service. You will send an HTTP GET request to a specific URL, including your API key and the address you wish to geocode as query parameters. The API will respond with a JSON object containing the geocoded results.

Example Geocoding Request (cURL):

Open your terminal or command prompt and execute the following cURL command. Replace YOUR_API_KEY with the actual API key you retrieved from your Cartes.io dashboard.

curl "https://api.cartes.io/geocode?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY"

This command requests the coordinates for "1600 Amphitheatre Parkway, Mountain View, CA."

Expected JSON Response:

A successful response will return a JSON object similar to this example. The exact structure and content may vary slightly based on the query and API version, but it will generally include an array of results with location details.

{
  "results": [
    {
      "lat": 37.4224764,
      "lon": -122.0842499,
      "address": {
        "house_number": "1600",
        "road": "Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "California",
        "postcode": "94043",
        "country": "United States"
      },
      "boundingbox": [
        37.4219764,
        37.4229764,
        -122.0847499,
        -122.0837499
      ]
    }
  ],
  "query": {
    "text": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "status": "success"
}

The lat and lon fields provide the latitude and longitude, respectively. The address object contains parsed components of the input address. The status field indicates the success or failure of the request.

Common next steps

After successfully making your first geocoding request, consider these common next steps to further integrate Cartes.io into your application:

1. Explore Other Endpoints: Cartes.io offers reverse geocoding (converting coordinates to addresses) and search APIs. Review the Cartes.io API documentation to understand these endpoints and their parameters.
2. Implement Error Handling: Integrate robust error handling into your application to manage cases where the API returns an error status (e.g., invalid API key, rate limit exceeded, no results found). The API typically provides informative error messages in its JSON responses.
3. Manage Rate Limits: Be aware of the API's rate limits. The free tier allows 5,000 requests per month. For higher volumes, consider upgrading to a paid plan. Implement retry mechanisms with exponential backoff for rate-limited requests to avoid being blocked.
4. Secure Your API Key: Ensure your API key is not exposed in client-side code or public repositories. For server-side applications, store it in environment variables or a secure configuration management system.
5. Integrate with a Mapping Library: If you plan to display the geocoded results on a map, integrate a mapping library such as Leaflet, OpenLayers, or the Google Maps JavaScript API. These libraries can consume the latitude and longitude coordinates from Cartes.io and render interactive maps. For instance, the Google Maps JavaScript API provides tools for displaying markers and polygons.
6. Monitor Usage: Regularly check your Cartes.io dashboard to monitor your API usage and ensure you stay within your plan's limits. This helps prevent unexpected service interruptions.

Troubleshooting the first call

When making your initial API request, you might encounter issues. Here are common problems and their solutions:

• Invalid API Key:
  • Symptom: The API returns an error message indicating an invalid or missing API key, or a 401 Unauthorized HTTP status code.
  • Solution: Double-check that you have copied the API key correctly from your Cartes.io dashboard. Ensure there are no leading or trailing spaces. Verify that the key is included in the request URL as specified in the Cartes.io API documentation.
• Incorrect Endpoint URL:
  • Symptom: The API returns a 404 Not Found HTTP status code or a generic error.
  • Solution: Verify that the base URL and endpoint path are correct (e.g., https://api.cartes.io/geocode). Compare your URL against the examples provided in the Cartes.io API reference.
• Missing or Malformed Query Parameters:
  • Symptom: The API returns an error indicating missing required parameters (e.g., q for geocoding) or a 400 Bad Request HTTP status code.
  • Solution: Ensure all mandatory query parameters are present and correctly formatted. For example, the address query (q) should be URL-encoded, especially if it contains spaces or special characters. Many HTTP clients, like cURL, handle basic URL encoding automatically, but complex strings might require explicit encoding. The Mozilla Developer Network's URL encoding guide provides further details.
• Rate Limit Exceeded:
  • Symptom: The API returns a 429 Too Many Requests HTTP status code.
  • Solution: This indicates you have exceeded your plan's request limit. Wait for the rate limit to reset, or consider upgrading your Cartes.io plan. Implement client-side rate limiting or caching to reduce the number of API calls if possible.
• Network Connectivity Issues:
  • Symptom: The request times out, or you receive a network-related error message from your HTTP client.
  • Solution: Check your internet connection. Ensure there are no firewall rules or proxy settings blocking outgoing HTTP requests from your environment to api.cartes.io.
• Unexpected JSON Response Structure:
  • Symptom: The API returns a successful status, but the JSON response does not match the expected format, making it difficult to parse.
  • Solution: Refer to the Cartes.io API documentation for the exact structure of successful responses. The API may return different fields or nested objects depending on the specific query or API version.