{"id":7392,"library":"mapbox","title":"Mapbox Python SDK","description":"The Mapbox Python SDK is an official client library for interacting with various Mapbox APIs, including Geocoding, Directions, Matrix, Static Images, and Uploads. It simplifies API requests and response handling. The current version is 0.18.1, and it maintains an active development cadence with regular updates addressing API changes and new features.","status":"active","version":"0.18.1","language":"en","source_language":"en","source_url":"https://github.com/mapbox/mapbox-sdk-py","tags":["geospatial","mapping","api-client","location"],"install":[{"cmd":"pip install mapbox","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Service clients are imported directly from the mapbox package, not accessed via the top-level module.","wrong":"import mapbox; client = mapbox.Geocoder()","symbol":"Geocoder","correct":"from mapbox import Geocoder"},{"symbol":"Directions","correct":"from mapbox import Directions"},{"symbol":"Matrix","correct":"from mapbox import Matrix"},{"symbol":"Static","correct":"from mapbox import Static"},{"symbol":"Uploads","correct":"from mapbox import Uploads"},{"note":"A generic client for advanced use cases or when a specific service client isn't available.","symbol":"Mapbox","correct":"from mapbox import Mapbox"}],"quickstart":{"code":"import os\nfrom mapbox import Geocoder\n\n# Ensure your Mapbox access token is set as an environment variable (e.g., export MAPBOX_ACCESS_TOKEN=\"sk.YOUR_SECRET_TOKEN\")\n# For server-side APIs like Geocoding, a secret (sk.) token is usually required.\naccess_token = os.environ.get('MAPBOX_ACCESS_TOKEN', 'YOUR_MAPBOX_SECRET_TOKEN')\n\nif access_token == 'YOUR_MAPBOX_SECRET_TOKEN':\n    print(\"WARNING: MAPBOX_ACCESS_TOKEN environment variable not set or placeholder used.\\nPlease set it to your actual Mapbox secret access token for the quickstart to function.\")\n    # Using a dummy token for code structure, this will fail API calls.\n    access_token = \"sk.dummy_token_for_example\"\n\ngeocoder = Geocoder(access_token=access_token)\n\n# Perform a forward geocode lookup\nresponse = geocoder.forward('1600 Amphitheatre Pkwy, Mountain View, CA')\n\nif response.status_code == 200:\n    data = response.json()\n    if data and data.get('features'):\n        first_result = data['features'][0]\n        print(f\"Location: {first_result['place_name']}\")\n        print(f\"Coordinates (lon, lat): {first_result['center']}\")\n    else:\n        print(\"No features found.\")\nelse:\n    print(f\"Error: {response.status_code} - {response.json().get('message', 'Unknown error')}\")","lang":"python","description":"This quickstart demonstrates how to initialize the Mapbox Geocoder client using an access token from an environment variable and perform a basic forward geocode lookup. For server-side APIs, ensure you use a secret (sk.) access token with appropriate scopes."},"warnings":[{"fix":"Migrate your code to use the `Matrix` API for distance calculations. The `Matrix` API offers more flexibility, including one-to-many and many-to-many calculations.","message":"The `Distance` API was deprecated and removed in favor of the more comprehensive `Matrix` API.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"Ensure that the `MAPBOX_ACCESS_TOKEN` you provide to the client is a *secret* token (`sk.`) with the necessary scopes enabled. Check your Mapbox account dashboard to generate or verify tokens.","message":"Using the wrong type of Mapbox access token for server-side APIs (e.g., Geocoding, Directions). Many Mapbox services require a *secret* access token (starting with `sk.`) for server-side requests, while *public* tokens (starting with `pk.`) are typically for client-side map display and have limited API access.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always review the release notes carefully when upgrading to a new minor version (e.g., 0.18.0, 0.19.0) to identify any breaking changes or required code adjustments.","message":"As the library is pre-1.0 (currently 0.x.x), minor version updates (e.g., from 0.17.x to 0.18.x) *can* introduce breaking changes without a major version bump, deviating from strict semantic versioning.","severity":"breaking","affected_versions":"All pre-1.0 versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install mapbox` to install the library.","cause":"The 'mapbox' package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'mapbox'"},{"fix":"Double-check your `MAPBOX_ACCESS_TOKEN` for typos. Ensure it is a *secret* token (`sk.`) and has the required scopes enabled for the specific Mapbox API you are calling (e.g., `geocoding:forward` for Geocoding). You can generate/manage tokens in your Mapbox account dashboard.","cause":"The Mapbox access token provided is either incorrect, expired, or does not have sufficient permissions for the requested API. A common cause is using a public (pk.) token for a server-side API that requires a secret (sk.) token.","error":"mapbox.errors.InvalidAccessTokenError: Unauthorized - Invalid Token"},{"fix":"Change your import statement to `from mapbox import Geocoder` (and other service clients you need, e.g., `Directions`, `Matrix`).","cause":"You likely imported the entire `mapbox` module (e.g., `import mapbox`) and then tried to access a service client like `mapbox.Geocoder()`. The service clients are meant to be imported directly.","error":"AttributeError: 'module' object has no attribute 'Geocoder'"},{"fix":"Check your internet connection and any proxy settings. If occurring frequently, verify your `MAPBOX_ACCESS_TOKEN` is correct and not rate-limited. Implement retry logic for transient network issues. If using a custom Mapbox host, ensure it's correctly configured.","cause":"This error can occur if there's a problem with the network connection, a proxy issue, or if the Mapbox API rejects the request very early (e.g., due to malformed headers, extremely rapid requests triggering rate limits, or invalid token even before a proper HTTP response).","error":"requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))"}]}