You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
CartoDB Voyager now displays “API KEY REQUIRED” #414
Hi,
I have just started using Map View and noticed that the default CartoDB Voyager map source now displays an “API KEY REQUIRED” watermark.
My Map View configuration uses:
Geosearch provider: OpenStreetMap / Nominatim
Map source: CartoDB Voyager
Would it be possible to:
update the default CartoDB Voyager URL if an API key is now required;
provide a built-in basemap that does not require an API key;
Thanks for maintaining Map View — the geosearch and inline geo: links work very well.
I have found a workaround for the recent CARTO API KEY REQUIRED issue.
I contacted CARTO support and was able to obtain a free API key for personal use. They provided me with the following tile URL: https://basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=MY_KEY
The key can be requested here: CARTO — Basemap API key
I added this URL as a second Map View map source, named CartoDB API.
However, I cannot make this source the default source. This appears to be related to the problem described in #402: when I select CartoDB API and then try to save it as the Default preset, Map View returns to the original CartoDB source.
I found two workarounds:
For embedded maps: manually change the chosenMapSource value in the mapview embed from 0 to 1:
"chosenMapSource":1
0 selects the original CartoDB source and 1 selects my new CartoDB API source.
Alternatively: replace the URL of the original CartoDB source with the authenticated CARTO URL above. This also works, because the existing default source then uses the API key.
So the CARTO API key itself works correctly. The remaining issue is that I cannot reliably make the new authenticated source the default Map View source.
It would be useful if the default map source could be changed reliably, or if the Default preset could correctly save the selected map source.
Thank you.
Same issue here! Happy to see that it's a new issue. I'm on the cutting edge. ;)
Also, in the process of troubleshooting and going back through the Quick Start Docs, I noticed something confusing.
In Option 1 for OpenStreetMap, it says to open the Map View Settings and then find "Geosearch email address", but it doesn't say that anywhere in the Map View options. It says "Geocoding search provider" and "OpenStreetMap user email", but definitely doesn't say "Geosearch email address".
I know it's a small detail, but for beginners and people trying to read along and make sure they are getting every word, it can throw someone off. I'm happy to whip up a quick little PR to fix it -> #415 !!
And also, while I'm here, it's interesting to learn that this plugin uses carto.com. I thought we were configuring OpenStreetMap, but even then when I look in the corner of the Map View it says Leaflet & OpenStreetMap! Holy Moly! How many different chunks of the map are divided up like that!?! Interesting to see how the pieces fit together. Why can't we just use OpenStreetMap? Why does it also require carto and leaflet? This is really just a curiosity for me at this point, feel free to ignore!
Results - with a couple of the messages highlighted:
Setup:
SYSTEM INFO:
Obsidian version: 1.14.0
Installer version: 1.12.7
Operating system: Darwin Kernel Version 25.5.0: Tue Jun 9 22:28:34 PDT 2026; root:xnu-12377.121.10~1/RELEASE_ARM64_T6041 25.5.0
Login status: logged in
Language: en
Catalyst license: vip
Insider build toggle: on
Live preview: on
Base theme: adapt to system
Community theme: none
Snippets enabled: 0
Restricted mode: off
Plugins installed: 1
Plugins enabled: 1
1: Map View v6.1.4
RECOMMENDATIONS:
Community plugins: for bugs, please first try updating all your plugins to latest. If still not fixed, please try to make the issue happen in the Sandbox Vault or disable community plugins.
Oh, but interestingly the API KEY REQUIRED overlay does not appear on my (new) iPad.
It's the same vault as on my Mac (synced with Obsidian Sync).
Is it device-specific, or has the problem gone away?
Thanks everybody for the contribution to understanding this issue!
The biggest problem left, I think, is that CartoDB Voyager no longer seems to be suitable for the free, no-registration-needed default :(
If someone knows an alternative, would love to know.
I played around with other mapping tiling stuff, and was able to use the basic OpenStreetMap tile url:
https://tile.openstreetmap.org/{z}/{x}/{y}.png
Which results in this mapping here...
It works, it doesn't require an API KEY, but I can't figure out how to make that the default view. At times it keeps popping back to CartoDB. Like, even after I have set OSM as the mapping view, if I click the "Show on map" option from the ••• menu, it takes me to the "Interactive Map View" which is different than the Map View within the Base, and that view always defaults to CartoDB mapping.
I even tried just completely replacing the CartoDB tile url one with OSM in the settings, but when I refresh the plugin, I get this pop-up notification...
Which is the plugin forcing CartoDB back in as the default mapping view. So, I have a bit of a solution, but it doesn't exactly work as I would hope at the moment.
It's certainly possible to just put the basic OSM tile url in as the default view, completely replacing CartoDB at the code level. That seems like one option, but, in general the basic OSM tiles aren't as pretty looking as the CartoDB ones.
Another option is for you (us!) to get just a CartoDB Voyager API KEY that could be used by this plugin at the default level? It seems like the process is pretty simple and straight-forward, doesn't require a CARTO account, and allows for 5 MILLION tile requests per month. Seems like possibly the easiest solution to this problem at the moment.
Also, something to consider... would it be possible to adjust the code to allow for us to select a Default Map Source? Like, it's well and good that I can add new map view sources! It's really cool actually, and it's kind of inspiring me to look around at some of the other options and possibly get an API KEY from one of the others that I really like and just going that route. But, knowing that I can set that map source as the default makes those options less appealing.
OpenStreetMap is awesome, but their terms of use do not allow making their server the default for an app.
Any map source you define can be made your own default via the Presets drop-down -> Save as Default.
One confusing issue is that Obsidian often retains states of views, and when you close and open Obsidian, you get a saved state and not Map View's default. To make sure you truly "reset" your default to what you want it to be, close any Map View tabs, then open a new one, and make sure OpenStreetMap (or whatever you wanted set) is the one opened. From that point, you should not be getting your old default jumping in.
5M tile requests per month is not enough for one API key to be used :-/ It qualifies for a few hundred power users.
The native Obsidian Maps plugin uses OpenFreeMap, which indeed have a great free license. However, this comes at a great cost: it is a vector-only map. While adding vector map support to Map View is certainly a worthy effort, I didn't do it yet -- well, because I personally dislike vector maps so I had other priorities 🤷 (but a vector map is considerably cheaper to host and serve than tiles, and therefore OpenFreeMap can afford to offer it for free.)
I can't seem to find this "Presets drop-down" that you are referring to. Can you help point me in the right direction for that?
It remembers my map source in all scenarios accept when selecting "Show on map" from the ••• menu on a specific page. That takes me to the "Interactive Map View" which is different than all other map views that I am aware of. It's not a base, it's not a normal view, it's sort of its own map view. Does that make sense? Did you watch the screen recording video that I linked to in my last comment? That shows what I am seeing very clearly.
Understood.
Interesting! I can understand how vector maps would be cheaper to host.
Map View can be opened as an independent view, as a Bases view, or as an
inline map.
In the full view, you have a few drop-downs on the top left corner:
Filters, View, Links, Presets and Edit. In Presets, you can set the global
default.
OK, I found that eventually, but the default doesn't seem to make much of a difference as far as I can tell. I will keep playing with it, but if it keeps behaving the way I am seeing, I will send another screen recording so you can see what I am seeing. Thanks for your help!
Am I using it right? As you can see, it doesn't really matter what I do with the preset or the default, because every time that I go back to the "Show on map" option, the View drop down resets back to CartoDB.
It seems to me that the Preset is something different than the map source, is that right?
What I am imagining is something here in the Map View Settings...
Where maybe I could drag and drop or something to put OSM above CartoDB, so that in all scenarios it selects that option FIRST as the default. Does that make sense?
Okay! Update! I don't know what I did different this time, maybe it was saving my Preset as "OSM Preset" instead of "OSM", which maybe was causing some naming conflicts, but I got the "Show on map" option to load up the OSM map. That's great! Thanks again for your help with that.
To isolate the variables, can you try the following:
Open Map View (as an independent view, like shown in the video, on which you see all the drop-downs).
Switch the map source to OSM, then click to save as default, just like in the video. Make sure the preset drop-down switches to show "default" -- just like in the video.
Then, close all Obsidian tabs, and just launch Map View again the same way, as a full view. What map source is shown in this case?
Additionally:
I see in the video you're also launching Map View as a Base. In the base view settings (view name -> opens a Configure View menu), under View, try to change Map Source. Does this make a difference? Perhaps the Base settings are unintentionally affecting your default (which is a bug to isolate). Hope the above is clear enough, as the word View is confusing 😓
Can you send over your data.json file from the Map View settings (under VAULT_DIR/.obsidian/plugins/obsidian-map-view)?
OpenStreetMap is awesome, but their terms of use do not allow making their server the default for an app.
Any map source you define can be made your own default via the Presets drop-down -> Save as Default.
One confusing issue is that Obsidian often retains states of views, and when you close and open Obsidian, you get a saved state and not Map View's default. To make sure you truly "reset" your default to what you want it to be, close any Map View tabs, then open a new one, and make sure OpenStreetMap (or whatever you wanted set) is the one opened. From that point, you should not be getting your old default jumping in.
5M tile requests per month is not enough for one API key to be used :-/ It qualifies for a few hundred power users.
The native Obsidian Maps plugin uses OpenFreeMap, which indeed have a great free license. However, this comes at a great cost: it is a vector-only map. While adding vector map support to Map View is certainly a worthy effort, I didn't do it yet -- well, because I personally dislike vector maps so I had other priorities 🤷 (but a vector map is considerably cheaper to host and serve than tiles, and therefore OpenFreeMap can afford to offer it for free.)
Hi there, curious to know why you dislike vector maps. What limitations do you see? Other Obsidian plug-ins are using OpenFreeMap as well.
If you offer it as an option, please provide users with a button to sponsor the OpenFreeMap project (to help cover hosting costs). Thanks!
Just to clarify: I would like to add support for vector layers, just haven't gotten around to it, and as a solo hobby project, personal preferences matter :)
I personally like dense, feature-rich maps, showing a lot of information at once. Vector maps generally don't do that, though in theory they can, but the more features you add, the bigger and more costly to render they become...
To isolate the variables, can you try the following:
Open Map View (as an independent view, like shown in the video, on which you see all the drop-downs).
Switch the map source to OSM, then click to save as default, just like in the video. Make sure the preset drop-down switches to show "default" -- just like in the video.
Then, close all Obsidian tabs, and just launch Map View again the same way, as a full view. What map source is shown in this case?
Additionally:
I see in the video you're also launching Map View as a Base. In the base view settings (view name -> opens a Configure View menu), under View, try to change Map Source. Does this make a difference? Perhaps the Base settings are unintentionally affecting your default (which is a bug to isolate). Hope the above is clear enough, as the word View is confusing 😓
Can you send over your data.json file from the Map View settings (under VAULT_DIR/.obsidian/plugins/obsidian-map-view)?
@esm7 Hey hey! Thanks for your patience with me. I am finally getting around to digging in deep on this! I went back and forth, up and down, I installed and uninstalled the plugin at least a couple dozens of times trying out different scenarios, and here's what I have learned...
In the Interactive Map View, after selecting a View (such as "MapTiler") and zooming in a little bit, if I don't click "Save as..." on the preset, then the "Save as Default" does not work. I can't figure out how to just force a non-saved preset to become the default.
If go through that same flow but this time I DO click "Save as...", make a "MapTiler Preset", and then immediately click "Save as Default", it does not save the default.
If I go back through that same flow, select the View as "MapTiler", then select the "MapTiler Preset", and then hit "Save as Default", it once again does not save. I can repeat this flow over and over and over, each time it fails. Open the map view, select the view, select the preset, save as default, it fails. Over and over again. ON repeat.
BUT THEN, if I open the Interactive Map View and do NOT set the view, but instead go right away to the Preset menu, select "MapTiler Preset", and then hit "Save as Default" it works!! Holy moly! It works!
Here's a video of my running through that loop a couple times...
I did a bunch of side by side comparisons of my own snapshots of that data at different moments in all my testing. In the end, the different between when it was working and wasn't working all came down to the chosenMapSource of the defaultState. In the looping scenario where it wasn't saving the default, that value would remain at 0, which corresponds to CartoDB (the first element in the mapSources array -> array[0]). In the scenarios where it did save the default and was behaving as hoped and expected, that value would be 1, which corresponds to MapTiler (the second element in the mapSources array -> array[1]).
Makes sense to me! It's just having a hard time actually saving the default went the view is selected first... I THINK! 🤔
Oh, also, the Map View as a Base is working flawlessly. Setting the View in the "Configure view" menu works great with no problems. Easy peasy. So, you don't need to worry about that part.
Let me know if there's anything else you might need help with!
I have found a workaround for the recent CARTO API KEY REQUIRED issue. I contacted CARTO support and was able to obtain a free API key for personal use. They provided me with the following tile URL: https://basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=MY_KEY The key can be requested here: CARTO — Basemap API key I added this URL as a second Map View map source, named CartoDB API.
I did the same (with an aquired API key from Carto), but when copying your URL from your comment, it copies the URL-encoded version with { and } escaped, which yields an error message: "unable to load map tiles".
Manually replacing the escaped characters works, as well as copying the URL text instead of the URL. By the way, adding the API key to the default Map View URL doesn't work because of the {s} subdomain in the beginning - just in case someone else runs into this issue.
Thankfully, the OpenStreetMap URL @eliduke provided in their comment (also) works flawlessly out of the box for me, without an API key.
(I'd much prefer vector-based maps, though, as the mobile network connectivity in my country is sometimes abysmal. Vector-based maps would also allow for better caching without taking up too much space. I know it's "planned" already, just wanted to provide my motivation.)
P.s. @xrauphoenix you might want to remove the utm_source=chatgpt from your provided URL(s), lol. :D
MapTiler is definitely fancy. I'd probably use that in my own projects. But for now I have two working maps and no real preference between them as long as I still get rasterized tiles. Thanks for the recommendation, though!
Activity
Torajirosan commentedon Sep 1, 2026
Same issue here.
xrauphoenix commentedon Sep 1, 2026
I have found a workaround for the recent CARTO API KEY REQUIRED issue.
I contacted CARTO support and was able to obtain a free API key for personal use. They provided me with the following tile URL:
https://basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=MY_KEY
The key can be requested here:
CARTO — Basemap API key
I added this URL as a second Map View map source, named CartoDB API.
However, I cannot make this source the default source. This appears to be related to the problem described in #402: when I select CartoDB API and then try to save it as the Default preset, Map View returns to the original CartoDB source.
I found two workarounds:
"chosenMapSource":1
0 selects the original CartoDB source and 1 selects my new CartoDB API source.
So the CARTO API key itself works correctly. The remaining issue is that I cannot reliably make the new authenticated source the default Map View source.
It would be useful if the default map source could be changed reliably, or if the Default preset could correctly save the selected map source.
Thank you.
eliduke commentedon Sep 2, 2026
Same issue here! Happy to see that it's a new issue. I'm on the cutting edge. ;)
Also, in the process of troubleshooting and going back through the Quick Start Docs, I noticed something confusing.
In Option 1 for OpenStreetMap, it says to open the Map View Settings and then find "Geosearch email address", but it doesn't say that anywhere in the Map View options. It says "Geocoding search provider" and "OpenStreetMap user email", but definitely doesn't say "Geosearch email address".
I know it's a small detail, but for beginners and people trying to read along and make sure they are getting every word, it can throw someone off. I'm happy to whip up a quick little PR to fix it -> #415 !!
And also, while I'm here, it's interesting to learn that this plugin uses carto.com. I thought we were configuring OpenStreetMap, but even then when I look in the corner of the Map View it says Leaflet & OpenStreetMap! Holy Moly! How many different chunks of the map are divided up like that!?! Interesting to see how the pieces fit together. Why can't we just use OpenStreetMap? Why does it also require carto and leaflet? This is really just a curiosity for me at this point, feel free to ignore!
claremacrae commentedon Sep 5, 2026
Here is a reproduction:
Results - with a couple of the messages highlighted:
Setup:
claremacrae commentedon Sep 6, 2026
Oh, but interestingly the API KEY REQUIRED overlay does not appear on my (new) iPad.
It's the same vault as on my Mac (synced with Obsidian Sync).
Is it device-specific, or has the problem gone away?
eliduke commentedon Sep 6, 2026
That could be because some of the map tiles on your iPad were cached from before the
API KEYwas required.esm7 commentedon Sep 6, 2026
Thanks everybody for the contribution to understanding this issue!
The biggest problem left, I think, is that CartoDB Voyager no longer seems to be suitable for the free, no-registration-needed default :(
If someone knows an alternative, would love to know.
eliduke commentedon Sep 6, 2026
I've been doing some digging and I have some follow-up thoughts and questions...
-> Can you help us understand exactly how the three bits fit together: OpenStreetMap + Leaflef + CartoDB?
I was always under the impression that OpenStreetMap could do all of these things.
-> Why is CartoDB Voyager needed at all?
-> Or, is the hard part finding another "free, no-registration-needed" option?
I have also been playing around the "default" Obisidian Maps plugin, and it looks like they use MapLibre...
https://maplibre.org
And I'm assuming that are looking for "interactive vector tile maps in the browser" right?
https://github.com/maplibre/maplibre-gl-js/
I'm more than happy to keep looking into things and tinkering with other options.
eliduke commentedon Sep 6, 2026
I played around with other mapping tiling stuff, and was able to use the basic OpenStreetMap tile url:
Which results in this mapping here...
It works, it doesn't require an API KEY, but I can't figure out how to make that the default view. At times it keeps popping back to CartoDB. Like, even after I have set OSM as the mapping view, if I click the "Show on map" option from the
•••menu, it takes me to the "Interactive Map View" which is different than the Map View within the Base, and that view always defaults to CartoDB mapping.Click here for a screen recording of what I am seeing on my end
I even tried just completely replacing the CartoDB tile url one with OSM in the settings, but when I refresh the plugin, I get this pop-up notification...
Which is the plugin forcing CartoDB back in as the default mapping view. So, I have a bit of a solution, but it doesn't exactly work as I would hope at the moment.
It's certainly possible to just put the basic OSM tile url in as the default view, completely replacing CartoDB at the code level. That seems like one option, but, in general the basic OSM tiles aren't as pretty looking as the CartoDB ones.
Another option is for you (us!) to get just a CartoDB Voyager API KEY that could be used by this plugin at the default level? It seems like the process is pretty simple and straight-forward, doesn't require a CARTO account, and allows for 5 MILLION tile requests per month. Seems like possibly the easiest solution to this problem at the moment.
Also, something to consider... would it be possible to adjust the code to allow for us to select a Default Map Source? Like, it's well and good that I can add new map view sources! It's really cool actually, and it's kind of inspiring me to look around at some of the other options and possibly get an API KEY from one of the others that I really like and just going that route. But, knowing that I can set that map source as the default makes those options less appealing.
Thanks again!
esm7 commentedon Sep 7, 2026
eliduke commentedon Sep 7, 2026
•••menu on a specific page. That takes me to the "Interactive Map View" which is different than all other map views that I am aware of. It's not a base, it's not a normal view, it's sort of its own map view. Does that make sense? Did you watch the screen recording video that I linked to in my last comment? That shows what I am seeing very clearly.esm7 commentedon Sep 7, 2026
eliduke commentedon Sep 7, 2026
OK, I found that eventually, but the default doesn't seem to make much of a difference as far as I can tell. I will keep playing with it, but if it keeps behaving the way I am seeing, I will send another screen recording so you can see what I am seeing. Thanks for your help!
eliduke commentedon Sep 7, 2026
I tried playing around with the Presets drop down default stuff, and I can't really figure out what is going on. Here are my attempts...
Map View Screen Recoding
Am I using it right? As you can see, it doesn't really matter what I do with the preset or the default, because every time that I go back to the "Show on map" option, the View drop down resets back to CartoDB.
It seems to me that the Preset is something different than the map source, is that right?
What I am imagining is something here in the Map View Settings...
Where maybe I could drag and drop or something to put OSM above CartoDB, so that in all scenarios it selects that option FIRST as the default. Does that make sense?
eliduke commentedon Sep 7, 2026
Okay! Update! I don't know what I did different this time, maybe it was saving my Preset as "OSM Preset" instead of "OSM", which maybe was causing some naming conflicts, but I got the "Show on map" option to load up the OSM map. That's great! Thanks again for your help with that.
esm7 commentedon Sep 7, 2026
To isolate the variables, can you try the following:
Additionally:
rubcap commentedon Sep 10, 2026
Hi there, curious to know why you dislike vector maps. What limitations do you see? Other Obsidian plug-ins are using OpenFreeMap as well.
If you offer it as an option, please provide users with a button to sponsor the OpenFreeMap project (to help cover hosting costs). Thanks!
esm7 commentedon Sep 11, 2026
Just to clarify: I would like to add support for vector layers, just haven't gotten around to it, and as a solo hobby project, personal preferences matter :)
I personally like dense, feature-rich maps, showing a lot of information at once. Vector maps generally don't do that, though in theory they can, but the more features you add, the bigger and more costly to render they become...
eliduke commentedon Sep 14, 2026
@esm7 Hey hey! Thanks for your patience with me. I am finally getting around to digging in deep on this! I went back and forth, up and down, I installed and uninstalled the plugin at least a couple dozens of times trying out different scenarios, and here's what I have learned...
Here's a video of my running through that loop a couple times...
https://assets.eliduke.com/map-view-screen-recording-4.mov
Now, regarding the
data.json...I did a bunch of side by side comparisons of my own snapshots of that data at different moments in all my testing. In the end, the different between when it was working and wasn't working all came down to the
chosenMapSourceof thedefaultState. In the looping scenario where it wasn't saving the default, that value would remain at0, which corresponds toCartoDB(the first element in themapSourcesarray ->array[0]). In the scenarios where it did save the default and was behaving as hoped and expected, that value would be1, which corresponds toMapTiler(the second element in themapSourcesarray ->array[1]).Makes sense to me! It's just having a hard time actually saving the default went the view is selected first... I THINK! 🤔
Here's some of the data dumps...
https://assets.eliduke.com/map-view-data.json
https://assets.eliduke.com/map-view-data-working.json
Oh, also, the Map View as a Base is working flawlessly. Setting the View in the "Configure view" menu works great with no problems. Easy peasy. So, you don't need to worry about that part.
Let me know if there's anything else you might need help with!
Thanks!
Panossa commentedon Oct 9, 2026
I did the same (with an aquired API key from Carto), but when copying your URL from your comment, it copies the URL-encoded version with
{and}escaped, which yields an error message: "unable to load map tiles".Manually replacing the escaped characters works, as well as copying the URL text instead of the URL. By the way, adding the API key to the default Map View URL doesn't work because of the
{s}subdomain in the beginning - just in case someone else runs into this issue.Thankfully, the OpenStreetMap URL @eliduke provided in their comment (also) works flawlessly out of the box for me, without an API key.
(I'd much prefer vector-based maps, though, as the mobile network connectivity in my country is sometimes abysmal. Vector-based maps would also allow for better caching without taking up too much space. I know it's "planned" already, just wanted to provide my motivation.)
P.s. @xrauphoenix you might want to remove the
utm_source=chatgptfrom your provided URL(s), lol. :Deliduke commentedon Oct 9, 2026
@Panossa OSM is great for personal use without an API Key! In the end though, it felt a little clunky and didn't look super clean.
I ended up going with MapTiler, which does require an API key, but it's totally free to sign up!
Here is the URL that works for me...
Really digging their Streets data set.
Panossa commentedon Oct 9, 2026
MapTiler is definitely fancy. I'd probably use that in my own projects. But for now I have two working maps and no real preference between them as long as I still get rasterized tiles. Thanks for the recommendation, though!