Home

android-chrome-192x192

Welcome to the BTC Map wiki! 🗺️

We're on a mission to help Bitcoiners easily find places to spend sats.

Our website and web app is at btcmap.org.

Check out our tagging instructions for details on how to get your locations showing in our apps and on OpenStreetMap.

Our API endpoints can be accessed at https://api.btcmap.org/v2/.

This documentation is organized into two sections. General for everything not developer related, and API which is meant to help you get started using our API and begin integrating bitcoin mapping data within your own apps.

Communities

BTC Map Communities are areas on the map, but they are also much more!

They are hubs of activity that connect local bitcoiners with each other and with local merchants. They provide focus for a community to help onboard new people and businesses to bitcoin.

You can add a community here, other useful links are the communities directory and leaderboard.

Each community gets their own page to track progress on BTC Map. You will receive a Grade based on your number of Up-To-Date locations. We provide all the metrics and data visualization needed to ensure you can maintain a high quality community in the bitcoin mapping context.

Bitcoin mapping communities maintain their local datasets and strive to have the most accurate information. Take ownership of your local data and help drive adoption. Bitcoin communities are the spark that ignites the movement. Join your friends and have fun!

Community Responsibilities 🧡

  • Help to onboard new users to bitcoin.

  • Maintain the merchants accepting bitcoin in your area. This means periodically verifying merchant details and making sure they are up-to-date on OpenStreetMap. See verified tags and the map legend for more details.

  • Help onboard new merchants to bitcoin and add them to the map.

Community Icon Specs

  • Preferred format is svg but webp, png or jpg will also be accepted.
  • The image should be square.
  • The image should have a background fill color (no transparent backgrounds).
  • Keep file sizes small.
  • Try to include some padding so that your icon looks good when the corners are rounded by apps.
  • The icon may be displayed on small screens so try to make it as readable as possible.

Content

Art 🎨

Podcasts 🎙️

Presentations 🧍

Videos 📹

Blogs / Articles 🖋️

Songs 🎶

Creating GeoJSON Areas

The BTC Map API uses Areas to calculate stats for Communities and Countries.

Originally, these areas were simple rectangles but we have now moved to polygons using the GeoJSON format. This provides much more accurate data.

GeoJSON polygon creation process

1. Find your area

Go to geojson.codingarena.top and search for your area (town, city, country).

image

Select your area from the search results.

image

2. Create your simplified polygon

You can view your polygon on the map and see the number of points it contains. Use the percentage buttons to reduce the number of points to no more than 150.

When you are happy with your polygon you can click on the blue Copy to clipboard button under the simplified GeoJSON.

image

3. Validate using linter (optional)

Your GeoJSON should be valid, but if you want to take an extra step and verify you can do this.

Go to geojsonlint.com and paste your GeoJSON into the textarea. Click the blue Test GeoJSON button. Any errors that need to be fixed will display in a popup modal. Once the code is valid there will be no errors and the area will be displayed on the website. If you receive the Polygons and MultiPolygons should follow the right-hand rule error you can visit this website to 'Rewind' and generate a new file.

4. Check population data

Please also add population and population:date information for the area in question.

There are Wikipedia links for the area which should contain information about the population that you can use.

image

5. Update the Issue

Save and attach the file as community-name.geojson to the relevant Issue.

6. Fin

One of the Admin team will make the update in the BTC Map DB.

Embedding

If you would like to embed the web map on your own website, simply add the following code to your HTML:

<iframe
  id="btcmap"
  title="BTC Map"
  width="600"
  height="300"
  allowfullscreen="true"
  allow="geolocation"
  src="https://btcmap.org/map"
>
</iframe>

You can adjust the width and height attributes to fit your page.

NOTE: If you want the geolocation feature to work you must also allow this in the Permissions Policy HTTP Header on the server of your website.

Permissions-Policy: geolocation=(self "https://btcmap.org")

For more information see this article.

If you would like the map the initialize on a specific location there are a couple more steps to complete

General area

  1. Visit btcmap.org/map and zoom the map to your desired location
  2. Copy the URL from your browser tab which contains geolocation data
  3. Add this URL to your iframe src attribute embed code

Communities map

  1. Use https://btcmap.org/communities/map for your iframe URL
Community area
  1. Use https://btcmap.org/communities/map?community=einundzwanzig-deutschland for your iframe URL (replace einundzwanzig-deutschland with the ID of your community - this can be found in the URL when visiting your community page)
Organization filter
  1. Use https://btcmap.org/communities/map?organization=einundzwanzig
Language filter
  1. Use https://btcmap.org/communities/map?language=es

If you would like to filter by payment method

Add the preferred payment method(s) as URLSearchParams to the src attribute of your iframe. These can be added in addition to the location params above.

The available options are:

  • onchain
  • lightning
  • nfc

Example: /map?onchain&lightning

Selecting a default basemap

To choose which basemap displays on page load, you can add the basemap param to your URL. The values correspond to the order they appear in the list on the map. For example, if you wanted to use the Terrain basemap you would add basemap=7. Like so: /map?basemap=7.

That's it!

Embedding is also possible on native mobile applications by utilizing the WebView.

Frequently Asked Questions 🙋‍♂️🙋‍♀️

How do I add a Pay Button?

Please contact hello@btcmap.org with your request.

This information is sensitive and cannot be stored in OpenStreetMap. It requires BTC Map to verify the information and store it in the BTC Map database.

How long does it take to add a Merchant?

That depends on the current backlog and how busy our community of volunteer Shadowy Suppertaggers are.

You will have received a GitHub Issue ID when you submitted the form where you can check progress, or you can reach out on our Discord. Here is a list of all open location submissions.

You can jump the queue by adding the location yourself in OpenStreetMap. Instructions are here. If you do this, please comment on your issue in GitHub so that we don't duplicate effort.

How long does is take to add a Community?

That depends on how busy our core team is, usually a few weeks maximum.

Here is a list of all open community submissions.

Integrations

Bitcoin projects integrating with BTC Map 🙏

Ways to integrate

  1. API
  2. Embed
  3. Payment buttons (contact us)
  4. Mapping
  5. A new integration?!

Projects

Have you integrated or featured BTC Map? Let us know!

Lightning Tips ⚡

There are lightning tip buttons in different places around BTC Map indicating that you can send a donation to one of our Shadowy Supertaggers for their contributions to the bitcoin mapping community.

Receiving tips

In order to receive tips and have your tip button appear on BTC Map you need to complete a few steps first.

  1. Create a lightning address or an LNURL-pay string

  • BTC Map supports either of these methods for accepting lightning payments. You can find a list of wallets that support both specs in the above links. You may already have a lightning address and not know, for example if you have a stacker.news account you can find your lightning address on your profile page. It only takes a few clicks to setup a lightning address with many of the wallets linked above and you can share your address in other places online to receive tips there as well.

  1. Add this information to your OpenStreetMap user profile

  • After logging into your OSM account, edit your profile description to include the following information: [⚡](lightning:btcmap@zbd.gg)
  • Replace btcmap@zbd.gg with your own lightning address or LNURL-pay string that you created in Step 1
  • Save your changes by clicking Update Profile

That's it! 🥳 You are now ready to receive lightning tips to your wallet for your contributions.

You will need to make an edit on OSM after updating your profile for the data to sync with BTC Map and it may take up to 24 hours.

Sending tips

To send lightning tips on BTC Map simply click on the Tip button and it will open any lightning enabled bitcoin wallet installed on your device. There are many lightning wallets to choose from. If you are using BTC Map on a desktop or laptop we recommend using the Alby browser extension for the most seamless experience.

Map Legend

Payment methods ₿

MethodAcceptedNot acceptedUnknown
On-chainimageimageimage
Lightningimageimageimage
Lightning contactlessimageimageimage

For more information on how these tags work you can check out our Tagging Instructions.

Verified

image

Locations with a Survey Date that is less than one year old will have a verified checkmark indicating that the information is most likely up-to-date. If you visit a location and are able to pay with bitcoin it is best practice to update the survey:date, check_date, or check_date:currency:XBT tag yourself. More information on which tag to use can be found here. Thanks for contributing to bitcoin open mapping!

Onboarding Merchants

A collection of resources to help onboard new merchants with accepting bitcoin as payment. 🤝

Hints and Tips

  • Simply ask "Cash or bitcoin" to raise awareness, particularly if you're a regular.
  • Ask your server if they would like their tip (maybe double it!) in bitcoin and have them download a simple custodial wallet like Wallet of Satoshi to get started; non-custodial can wait.
  • If you are speaking to the manager, don't necessarily try to Orange Pill them on day 1. Talk about bringing in more customers with very little effort.

Payment Providers

There are a number of merchant solutions to help vendors take payment in bitcoin and optionally convert to local fiat:

If you know of any other easy to use point-of-sale applications for new merchants please let us know!

Resources

Tools 🔨

Query and export data from OSM

Overpass Turbo

OpenStreetMap Resources 📚

Abuse

Automated Edits

Automated Edits - Code of Conduct

Best Practices

Bitcoin (OSM)

Cryptocurrency

Data Working Group

Good Changeset Comments

Import Guidelines

Licence Compatibility

Organised Editing Guidelines

Organised Editing - BTC Map

Source

Spam

taginfo

Verifiability

Wiki

https://wiki.openstreetmap.org/wiki/Main_Page

Community Forum

https://community.openstreetmap.org/

Services

Local services that accept bitcoin are great, however in order to be mapped they need to have a real physical location. OpenStreetMap rules state that verification is a key component to being eligible for mapping. This means that anyone should be able to visit the location and verify that it exists as described on the map. Services are accepted if they have an in-person location. If not, then there are other good options for being discovered by bitcoiners listed below:

Tagging Hashing Sites

For those wanting to tag locations that perform hashing (mining), you should use the following tags:

man_made=works

product=bitcoin

As described here: Tag:man_made=works.

AND

telecom=data_center

building=data_center

As described here: OSM Wiki - Telecoms-Datacenters and Tag:telecom=data_center.

AND OPTIONALLY

operator=* - The operator of the datacenter. In the case of a corporate datacenter, this will be the organisation which owns it. In the case of a colocation facility, this will be the colocation company.

name=* - The name of the datacenter.

owner=* - Some datacenters are constructed and owned by one company, but long-term leased in their entirety to another company to operate.

Tagging Instructions

Introduction

BTCMap.org uses an open source dataset provided by OpenStreetMap. If you are serious about supporting bitcoin adoption in your area, you should consider opening an OSM account and contributing to our mission to enable Bitcoiners to easily find places to spend sats anywhere on the planet.

Copyright

https://www.openstreetmap.org/copyright

OSM contributors are reminded never to add data from any copyrighted sources (e.g. Google Maps or printed maps) without explicit permission from the copyright holders.

Noobs 🙂

If you only want to add a few places and you aren't planning to maintain them, there is a simple form you can fill and our community will add your data to the OSM database. Our resources are limited so please consider learning how to add and edit data on OSM yourself if you have time.

If you want to verify information on an existing location there is also a simple form to do that.

You can learn more about OSM tagging in the Beginners Guide. We have also made a walkthrough video.

You can also slide into the BTC Map Discord if you have any questions. You'll be editing like a Shadowy Supertagger in no time!

Shadowy Supertaggers 🥷

Earn badges, sats and recognition on BTC Map for your contributions. Your efforts will be featured on our Activity Feed, Leaderboard and you will get your very own Tagger Profile too!

Once you have an OpenStreetMap account, you can use the OSM iD web app to edit the maps directly on OpenStreetMap.org.

A video tutorial can be found here.

Contributing

Add new or update existing locations directly as you see fit or help with the backlog of submissions from the Noob Form at one of the links below:

If you're a serious tagger, please consider joining the Shadowy Supertagger Team on GitHub so you can manage issues. We have a Supertagger Discord channel to get you onboarded.

Please use the following guidance when editing locations:

Physical Verification and Local Knowledge

Our main goal is to provide the public with an accurate data-set and locals know best. Please try to prioritize locations with close physical proximity to you. Make sure that you're relying on the most accurate data, such as:

  • On-site survey.
  • Direct phone/email (e.g.)/social media survey.
  • Various online sources (be careful about copyright), not all online data is free to use! The official website of the merchant is usually the best online source.

Relying on a form submission without any additional checks is discouraged. An extra step of due diligence should be taken to ensure we are adding accurate data to OpenStreetMap and being good stewards of the database.

Double-check Coordinates

If taking on issues submitted from the Add Location form, you can and should make adjustments to the exact pin location IF you notice it is incorrect. The person submitting the location will not be a mapping expert and that it ok - this is where the extra validation by the Supertagger can help improve the data accuracy. Any submissions with completely invalid locations (like in the middle of the ocean) can be closed as not-planned with the reason provided in a comment.

Source of Data

Each submission will contain information about the source of the data so that taggers will know if it was completed by the business owner, a customer, or by another method. Some submissions may also include contact information which can be used to follow-up if further information is required.

Tagging Guidance

Points, not Ways

Please tag points and not ways. If ways already exist, do not create any additional points and tag the existing ways instead. More information on element types can be found here.

Required Tags

currency:XBT=yes - This denotes the bitcoin currency is generally accepted, but doesn't specify the supported payment types.

currency:XBT=no - This denotes the bitcoin currency is not generally accepted.

The following tags drive the behavior of our apps and so please be as specific as you can when tagging.

payment:onchain=yes - Denotes that on-chain payments are accepted.

payment:onchain=no - Denotes that on-chain payments are not accepted.

payment:lightning=yes - This denotes that Lightning payments are accepted.

payment:lightning=no - This denotes that Lightning payments are not accepted.

payment:lightning_contactless=yes - This denotes that NFC Lightning payments are accepted.

payment:lightning_contactless=no - This denotes that NFC Lightning payments are not accepted.

Verified tags - more information

survey:date=yyyy-mm-dd - Use this tag when the location has been physically verified in person by you. Please use the correct ISO date format as shown.

check_date=yyyy-mm-dd - Use this tag when the location has been verified with local knowledge or extrapolation. Please use the correct ISO date format as shown.

check_date:currency:XBT=yyyy-mm-dd - You can reduce the scope of the information checked by using this tag. For example, if you had only checked the bitcoin tags. Please use the correct ISO date format as shown.

You should verify all the present tags (if possible) when you are adding bitcoin tags to an existing location.

Legacy Tags

payment:bitcoin=yes - This is a very popular legacy tag implying both currency:XBT=yes and payment:onchain=yes. You should remove the payment:bitcoin=yes tag when adding the currency:XBT=yes tag.

We still search for these legacy tags for general display in the apps, but we won't be specific on the payment types supported. You should really remove them when updating with the current tagging rules.

Here is the full list of the legacy places and you are encouraged to verify them. Clicking on any place in that list will open the OSM iD editor. If the place still exists, modify it using the guidance above. If the place doesn't exist, you can remove it from OSM. In a case when a place still exists but no longer accepts bitcoins, simply remove the payment:bitcoin=yes tag.

Other OpenStreetMap tags

OpenStreetMaps is an incredibly flexible platform with tags for a variety of different features.

Here are some useful links that may be useful for your location:

It is easy to look up all the available tags and their use-cases in the OSM Wiki.

Changeset Comments

Every edit on OpenStreetMap has the option to add a changeset comment. This is an important way for other OSM contributors to get a quick idea of what the edit contained. You can include a short description of your changes in this field.

Additionally, another OSM contributor may ask a question for clarification about one of your edits. You should receive an e-mail notification when this happens. Please make an effort to respond to any non-frivolous and respectful questions.

Please include the #btcmap hashtag in your changeset comments so that the activity is associated with our initiative.

Completing Issues

After you have added or edited a location on OpenStreetMap and before closing the GH Issue as complete, it is good practice to leave a comment listing any additional steps you took to verify the accuracy of the data. Please also paste a link to the changeset on OSM so others can reference it and provide additional comments if necessary.

Verifying Locations

Verify, don't trust. 🕵️

Does a location accept bitcoin?

You can verify this in a number of ways:

  • visit the location in person
  • phone the location
  • check their website or other online sources
  • ask a local in the area
  • contact via social media
  • send them an email

Once a location has been verified you can update the survey tags on OpenStreetMap so that the location will have a checkmark visible on BTC Map.

Below is an email template for the UK that you can use as a starting point and adapt it to contain correct information about your own local area.

Hello,

I appreciate that you are busy, so thank you for taking a couple of minutes to read and respond to this email. I'm part of a team of volunteers working on BTCmap.org - an open source map which shows all merchants which accept Bitcoin worldwide. According to OpenStreetMap data, your business accepts Bitcoin - or perhaps did so in the past!

Please can you reply to this email with the following information:

A) Yes, we still accept Bitcoin!

B) We no longer accept Bitcoin, but would be interested in accepting it in the future

C) We no longer accept Bitcoin and have no interest in accepting it in the future

Before you respond with Option C) you might want to consider that Bitcoin payments have come a long way in recent years...

  • The "Lightning network" allows Bitcoin to be sent near-instantly with very low fees - you can even accept contactless Bitcoin card payments!
  • Services such as CoinCorner allow you to automatically convert the Bitcoin you receive into GBP.
  • There is a growing community of bitcoiners who want to spend their "sats". Accept it and they will come!
  • Free and impartial advice on getting started is available from Bridge2Bitcoin.

I look forward to hearing from you soon. Happy to chat and answer any questions that you may have!

All the best,

Matt

Outdated Locations

As Satoshi Nakamoto clearly stated, Bitcoin is an electronic cash system, and the best way to accelerate Bitcoin adoption is to create a circular enomomy.

Having a map of all participating merchants is how we can bootstrap new regions. All bitcoiners should be able to find each other and trade goods and services without touching the fiat infrastructure. That's what we're working on, and we need your help.

Nothing lasts forever, and our merchants are no exception. Some shops may go out of business or just move across the street. That's why we need to check them from time to time. We're attempting to check every merchant at least once per year, and we can't do it without the help of local bitcoiners.

If you want to help us accelerate Bitcoin adoption, please read this simple step-by-step guide:

1. Find a Merchant on BTC Map

Let's say you're living in (or visiting) Kuala Lumpur, Malaysia, and you want to check the merchants nearby:

image

It looks like this cafe accepts Bitcoins, and the last verification date is 2024-01-28. In order to re-verify this place, you need to open it on OpenStreetMap. Click on the "Edit" button, you will need to create a OSM account if you don't already have one.

2. Update Merchant Details on OpenStreetMap

In the location editor:

image

Check that all fields are valid and accurate. If some fields are outdated or false, please update them.

3. Bump Check Date

Set the "Last Checked Date" field value to today's date and then press "Save":

image

image

Every OSM change requires a short description. If you only changed the check date, you can type "Bump check date". If you updated additional fields, you can mention that as well. After entering the changeset comment, hit the "Upload" button.

image

Note: There are other tags that can be used to verify a location including survey:date. The location you are editing may have one of those tags instead of the "Last Checked Date" tag. You can read more about the different verified tags here.

4. You're Awesome!

As you can see, verifying locations usually takes a couple of minutes, and everyone can do it.

Note: If you visited the location and found that the merchant no longer accepts bitcoin, you would simply remove the bitcoin-related tags from the merchant.

Merchant Best Practices

Here are a few tips and tricks which will help you boost your bitcoin sales.

Get a "Bitcoin Accepted" Sticker

Unfortunately, many bitcoiners don't know about BTC Map, and some of them may be your frequent customers. Putting a "Bitcoin Accepted" sticker at your entrance is a good way to target the "offline" audience.

image

Going all in is fun, but if it's not your cup of tea, a modest sticker wont hurt:

image

Mention Bitcoin Acceptance on Your Website or Socials

Make sure your online visitors get the same treatment as the offline ones. People want to know how they can pay you, so it's a good place to mention Bitcoin. It also makes it easier for others to verify your business and update your entry on BTC Map.

Consider Discounts for Bitcoiners

Everyone likes discounts, and bitcoiners are no exception. Offering a little discount may also help you convert a few locals, and it's always a good idea to expand our movement, which is critical for its success.

image

Train Your Staff

Don't forget to notify your staff that you started accepting bitcoins. Many merchants fail to do so, which is the most common source of user complaints. If you hire someone new, don't forget to include Bitcoin training in your onboarding process.

Check Your Records at Least Once a Year

If you followed the rest of the tips, you probably won't need to update your business details by yourself, it will be done automatically by your happy customers. You can always see the "last checked date" of your place on BTC Map. Make sure that date is no more than one year old. Here is a guide on keeping your listing up-to-date.

Introduction

Our API endpoints can be accessed at https://api.btcmap.org/v2/.

Endpoints

  • /elements
  • /events
  • /users
  • /areas
  • /reports

Data source

Most of the data included in the BTC Map API comes from OpenStreetMap data.

For BTC Map data we try to follow the same naming convention of keys as the OSM dataset.

Update interval

We sync with the OSM servers every 10 minutes to provide up-to-date open mapping data that is specific to bitcoin for everyone.

Standard keys

Every record in our tables will contain the following keys:

  • id
  • created_at
  • updated_at
  • deleted_at

You can link data from different tables together using the id.

Records are never removed, they only have the deleted_at field populated when they are deleted.

OpenStreetMap and BTC Map data contains many optional tags. It is good practice to check for the existence of a tag before referencing it to avoid undefined errors.

Caching

Applications can create local caches of the data and stay in sync with the BTC Map API. If a new record ID appears and you do not have it in your cache, you can assume it is a creation. You can discard cached records that have been updated.

Caching the data will allow for many improvements in your application like the ability to work offline, decrease loading times, reduce data usage and more. You can also incrementally sync the data by only fetching the records you need since your last update, instead of asking for all of the records in every request.

Status

You can check the status of the API and it's endpoints here. If you are experiencing any issues please reach out and let us know.

Elements

Endpoint

https://api.btcmap.org/v2/elements

Optional arguments

  • updated_since - ISO 8601 date
  • limit - 32-bit integer

Data

The elements endpoint contains an array of location objects pulled from OpenStreetMap. These locations are filtered from the complete OSM dataset by looking for one of the following tags:

  • currency:XBT=yes
  • payment:bitcoin=yes

More information about these tags and other bitcoin specific tags can be found in our data Wiki.

Reference to the OSM Wiki about elements can be found here. An element can contain many different tags which provide information about a given location. Reference to the OSM Wiki about tags can be found here.

Example

The osm_json key contains all of the information from OSM. The top level tags key contains BTC Map information which can include boosts, merchant lightning payment information, and other data.

{
  "id": "node:9985802993",
  "osm_json": {
    "changeset": 127516569,
    "id": 9985802993,
    "lat": 53.4423766,
    "lon": -2.2775673,
    "tags": {
      "addr:city": "Manchester",
      "addr:housenumber": "585A",
      "addr:postcode": "M21 9AF",
      "addr:street": "Wilbraham Road",
      "currency:GBP": "yes",
      "currency:XBT": "yes",
      "currency:others": "no",
      "description": "Inexpensive traditional barbers, no appointment needed.",
      "name": "RJ's",
      "opening_hours": "Mo-Sa 09:00-17:00",
      "payment:lightning": "yes",
      "payment:lightning_contactless": "yes",
      "payment:onchain": "yes",
      "phone": "+44 7812 919857",
      "shop": "hairdresser",
      "survey:date": "2022-10-14"
    },
    "timestamp": "2022-10-14T10:27:01Z",
    "type": "node",
    "uid": 16971158,
    "user": "nathan_day",
    "version": 11
  },
  "tags": {
    "category": "other",
    "icon:android": "content_cut",
    "issues": [
      { "description": "Out of date", "severity": 3382, "type": "out_of_date" }
    ]
  },
  "created_at": "2022-09-25T08:45:08Z",
  "updated_at": "2022-11-02T10:16:37Z",
  "deleted_at": ""
}

Additional endpoints and queries

Events

Endpoint

https://api.btcmap.org/v2/events

Optional arguments

  • updated_since - ISO 8601 date
  • limit - 32-bit integer

Data

The events endpoint contains an array of event objects. A new record gets added to this table when an element gets created, updated or deleted. Please note that when an element is created or deleted on BTC Map this does not necessarily mean the same event happened on OpenStreetMap. For example, if a currency:XBT=yes tag is removed on OSM - this element will be marked as deleted on BTC Map because it no longer accepts bitcoin. While on OSM the element still exists.

Another important note is that the events table does not contain a complete history of all events that happened on OSM. It only includes records since BTC Map has been operating.

Only events with a deleted_at value of an empty string "" are valid events. Non-valid events should be filtered out.

Example

{
  "id": 500,
  "type": "delete",
  "element_id": "node:2879194870",
  "user_id": 16971158,
  "created_at": "2022-10-11T10:03:39.549906728Z",
  "updated_at": "2022-10-11T10:03:39.549906728Z",
  "deleted_at": ""
}

Additional endpoints and queries

Users

Endpoint

https://api.btcmap.org/v2/users

Optional arguments

  • updated_since - ISO 8601 date
  • limit - 32-bit integer

Data

The users endpoint contains an array of user objects pulled from OpenStreetMap profiles. It does not contain every OSM user. A new record gets added to this table when an event is created and the users table does not yet have the profile information associated with this event. Once a user record is included, any changes made to the OSM profile will sync with the users table once daily.

We have been encouraging users to include a lightning address or LNURL-pay string in their profile descriptions so this information can be used to send them lightning tips. More information on the implementation can be found here.

Reference to the OSM Wiki about users can be found here.

Example

The osm_json key contains all of the information from OSM.

{
  "id": "17221642",
  "osm_json": {
    "account_created": "2022-09-24T01:06:05Z",
    "blocks": {
      "received": {
        "active": 0,
        "count": 0
      }
    },
    "changesets": {
      "count": 220
    },
    "contributor_terms": {
      "agreed": true
    },
    "description": "Lead on the ground of Bitcoin Island, Philippines.\r\nPowered by Pouch.ph",
    "display_name": "Bill on Bitcoin Island",
    "id": 17221642,
    "img": {
      "href": "https://www.openstreetmap.org/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBeno1MXc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--44266f623ba498d7db2aedf5321b5122087e5960/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCem9MWm05eWJXRjBTU0lJY0c1bkJqb0dSVlE2RkhKbGMybDZaVjkwYjE5c2FXMXBkRnNIYVdscGFRPT0iLCJleHAiOm51bGwsInB1ciI6InZhcmlhdGlvbiJ9fQ==--c51edbffdce997b8125dbbed51b6988fec44e09d/Bitcoin%20Island%20Square%20BG%20Trans.png"
    },
    "roles": [],
    "traces": {
      "count": 0
    }
  },
  "created_at": "2022-10-13T05:33:47Z",
  "updated_at": "2022-10-20T01:24:01Z",
  "deleted_at": ""
}

Additional endpoints and queries

Areas

Endpoint

https://api.btcmap.org/v2/areas

Optional arguments

  • updated_since - ISO 8601 date
  • limit - 32-bit integer

Data

The areas endpoint contains an array of area objects. An area can be any geographic area like a country, town, island etc. An area can also be a community like Bitcoin Island Philippines for example. These areas are manually added by BTC Map. Currently the primary purpose is to promote local bitcoin communities to take ownership of their bitcoin mapping data by managing it themselves, which will help drive adoption.

Polygon data can be found for areas in the GeoJSON format.

Example

{
  "id": "bitcoin-island-philippines",
  "tags": {
    "name": "Bitcoin Island Philippines",
    "type": "community",
    "continent": "asia",
    "population": "37802",
    "population:date": "2020-01-01",
    "geo_json": "<GeoJSON Polygon or MultiPolyon>",
    "contact:discord": "https://discord.gg/YAZjxHysQD",
    "contact:twitter": "https://twitter.com/BitcoinIslandPH",
    "contact:website": "https://pouch.ph/bitcoinisland",
    "icon:square": "https://btcmap.org/images/communities/bitcoin-island-philippines.jpg"
  },
  "created_at": "2022-10-15T04:12:56Z",
  "updated_at": "2022-10-19T20:40:21Z",
  "deleted_at": ""
}

Additional endpoints and queries

Communities

Community organizations with a medium or large amount of local bitcoin communities that are interested in joining BTC Map can reach out to a core team member to help facilitate a bulk upload of the data. Below describes the schema needed for each community and provides example values. Note that some fields are required and some are optional. Optional fields can be excluded from the dataset.

Example JSON

{
  "id": "bitcoin-ekasi", // should be all lowercase and spaces separated by `-` characters
  "tags": {
    "type": "community", // will always be `community`
    "name": "Bitcoin Ekasi",
    "continent": "africa", // can be one of the following options: `africa` `asia` `europe` `north-america` `oceania` `south-america`
    "icon:square": "https://btcmap.org/images/communities/bitcoin-ekasi.jpg",
    "contact:email": "hermann.unravelsurftravel@gmail.com", // can be any of the following options: `website` `email` `nostr` `twitter` `meetup` `eventbrite` `telegram` `discord` `youtube` `github` `reddit` `instagram` `whatsapp` `facebook` `linkedin` (at least one tag is required, new contact types can be requested)
    "contact:twitter": "https://twitter.com/BitcoinEkasi",
    "contact:website": "https://bitcoinekasi.com/",
    "tips:lightning_address": "example@getalby.com", // optional - can be a lightning address/lnurlp or a URL to a tip page using the `tip:url` format
    "organization": "african-bitcoiners",
    "language": "en", // optional
    "geo_json": "<GeoJSON Polygon or MultiPolyon>",
    "population": "2100", // optional
    "population:date": "2023-01-21" // optional
  }
}

Notes

  • GeoJSON can be created by following this guide or by using another method.
  • For community icon images please provide a zip file of all the assets and naming each file using the community id. See these specs for more details.

Reports

Endpoint

https://api.btcmap.org/v2/reports

Optional arguments

  • updated_since - ISO 8601 date
  • limit - 32-bit integer

Data

The reports endpoint contains an array of report objects. Statistics are checked every 24 hours and a new report is generated if there is a change in the data. If the latest report is not from the current date you can assume nothing has changed since then. Historical reports are immutable. Reports for the entire BTC Map dataset will have an area_id of an empty string "". Area specific reports will have a value in this field.

Example

{
  "id": 48,
  "area_id": "",
  "date": "2022-11-12",
  "tags": {
    "legacy_elements": 6528,
    "outdated_elements": 6952,
    "total_elements": 8623,
    "total_elements_lightning": 1483,
    "total_elements_lightning_contactless": 257,
    "total_elements_onchain": 1444,
    "up_to_date_elements": 1671
  },
  "created_at": "2022-11-12T00:01:39Z",
  "updated_at": "2022-11-12T00:01:39Z",
  "deleted_at": ""
}

Additional endpoints and queries

Wrap up

Thanks

Thanks for taking the time to read about BTC Map's API!

Feedback

BTC Map is an open source project so if you have any feedback for us please create an issue in this repo.

Integrations

If you have integrated your own application with our API please let us know, we would love to feature all of the projects sharing our data.

General

  • token
  • query
curl --data-binary '{"jsonrpc": "2.0", "method": "search", "params": {"password": "xxx", "query": "query", "id": 1}' https://api.btcmap.org/rpc

Example response to a berlin query param :

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": [
    {
      "id": 155,
      "name": "Bitcoin Berlin El Salvador",
      "type": "area"
    },
    {
      "id": 54,
      "name": "Berlin 2140",
      "type": "area"
    },
    {
      "id": 257,
      "name": "Einundzwanzig Berlin",
      "type": "area"
    },
    {
      "id": 77,
      "name": "Bitcoin Berlin El Salvador",
      "type": "area"
    }
  ]
}

Elements

get_element

  • token
  • id
curl --data-binary '{"jsonrpc": "2.0", "method": "get_element", "params": {"password": "xxx", "id": "node:12141608846"}, "id": 1}' https://api.btcmap.org/rpc

set_element_tag

  • token
  • name
  • value
curl --data-binary '{"jsonrpc": "2.0", "method": "set_element_tag", "params": {"password": "xxx", "id": "node:12141608846", "name": "foo", "value": "bar"}, "id": 1}' https://api.btcmap.org/rpc

remove_element_tag

  • token
  • id
  • tag
curl --data-binary '{"jsonrpc": "2.0", "method": "remove_element_tag", "params": {"password": "xxx", "id": "node:12141608846", "tag": "foo"}, "id": 1}' https://api.btcmap.org/rpc

boost_element

  • token
  • id
  • days
curl --data-binary '{"jsonrpc": "2.0", "method": "boost_element", "params": {"password": "xxx", "id": "node:12141608846", "days": 7}, "id": 1}' https://api.btcmap.org/rpc

add_element_comment

  • token
  • id
  • comment
curl --data-binary '{"jsonrpc": "2.0", "method": "add_element_comment", "params": {"password": "xxx", "id": "node:12141608846", "comment": "test comment"}, "id": 1}' https://api.btcmap.org/rpc

Areas

add_area

  • token
  • tags
curl --data-binary '{"jsonrpc": "2.0", "method": "add_area", "params": {"password": "xxx", "tags": {"url_alias": "test-area", "geo_json": {"type":"Point","coordinates":[0,0]}}}, "id": 1}' https://api.btcmap.org/rpc

get_area

  • token
  • id
curl --data-binary '{"jsonrpc": "2.0", "method": "get_area", "params": {"password": "xxx", "id": "test-area"}, "id": 1}' https://api.btcmap.org/rpc

set_area_tag

  • token
  • id
  • name
  • value
curl --data-binary '{"jsonrpc": "2.0", "method": "set_area_tag", "params": {"password": "xxx", "id": "test-area", "name": "foo", "value": "bar"}, "id": 1}' https://api.btcmap.org/rpc

remove_area_tag

  • token
  • id
  • tag
curl --data-binary '{"jsonrpc": "2.0", "method": "remove_area_tag", "params": {"password": "xxx", "id": "test-area", "tag": "foo"}, "id": 1}' https://api.btcmap.org/rpc
  • token
  • period_start
  • period_end
curl --data-binary '{"jsonrpc": "2.0", "method": "get_trending_countries", "params": {"password": "xxx", "period_start": "2024-01-01", "period_end": "2024-02-01"}, "id": 1}' https://api.btcmap.org/rpc
  • token
  • period_start
  • period_end
curl --data-binary '{"jsonrpc": "2.0", "method": "get_trending_communities", "params": {"password": "xxx", "period_start": "2024-01-01", "period_end": "2024-02-01"}, "id": 1}' https://api.btcmap.org/rpc

remove_area

  • token
  • id
curl --data-binary '{"jsonrpc": "2.0", "method": "remove_area", "params": {"password": "xxx", "id": "test-area"}, "id": 1}' https://api.btcmap.org/rpc

Contributors

Thanks for contributing to the bitcoin mapping community! 🙏