Getting started

This guide takes you from signing up to your first API request in a few minutes. You don't need a credit card: every account gets 250,000 free requests every 30 days.

1. Sign in

Go to app.mapricot.com and enter your email address. We'll email you an eight-digit code; enter it to sign in. There's no password to set.

2. Your account

An account holds your API keys, usage, and credit. You get one when you first sign in, named after you; rename it in Settings, for example to your company or project. If a teammate invited you, accept their invitation instead to join their account.

3. Create an API key

In your account, open API keys and press Create key. Give the key a name, and choose where it will be used:

  • Server, for code that runs on your servers or your own computer, and for mobile apps. Keep a server key secret: never put it in a web page. A mobile app sends no origin, so a browser key doesn't work there. Give an app's server key only the products it needs, and the caps below, since anyone who unpacks the app can read it.
  • Browser, for code in a web page. Anyone can read a key in a page, so it only works from the sites you allow, as browser keys explains.

Then pick the products it can use, which the API calls scopes:

  • Places (places) for geocoding and place search
  • Routing (routing) for routes
  • IP geolocation (ip-geolocation) for IP lookups

Copy the key when it's shown. A server key starts with mapricot_sk_ and a browser key with mapricot_pk_, and you won't be able to see it again. Store a server key as an environment variable rather than in your code:

export MAPRICOT_KEY="mapricot_sk_…"

Browser keys

A browser key works only from the sites listed under Allowed origins, one per line. An origin is a scheme, a host, and an optional port, with no path, such as https://example.com. *. matches any subdomain, as in https://*.example.com, and :* matches any port. Add http://localhost:* while you build, so the key works from pages served on your own computer.

A page opened straight from a file, with a file:// address, has no origin, so the API refuses every key there with 403 and "Key is not allowed from this origin." Serve the page with a local web server instead, such as npx serve or python3 -m http.server in its folder.

You can also cap a key's requests per minute and per 30 days, so a copied key can't use up your free requests or credit, and set a date it stops working. Give a browser key only the products the page needs.

4. Make a request

Search for an address:

Request
curl "https://api.mapricot.com/v1/search?q=128+SW+3rd+Ave,+Portland&limit=1" \
  -H "Authorization: Bearer $MAPRICOT_KEY"
Response
{  "attribution": [    {      "source": "openaddresses",      "text": "OpenAddresses",      "url": "https://openaddresses.io"    }  ],  "results": [    {      "id": "mp_b3BlbmFkZHJlc3NlczphZGRyZXNzOnVzL29yL211bHRub21haDpkZjdlYzM3YWJiYTJiNWM0",      "type": "address",      "name": "128 SW 3rd Avenue",      "label": "128 SW 3rd Avenue, Portland, OR, USA",      "lat": 45.521736,      "lon": -122.673276,      "address": {        "houseNumber": "128",        "street": "SW 3rd Avenue",        "postalCode": "97204",        "locality": "Portland",        "region": "Oregon",        "regionCode": "OR",        "country": "United States",        "countryCode": "US"      },      "source": "openaddresses"    }  ]}

The response lists matching places with their coordinates, address, and a Mapricot ID, plus the data credits to show if you display them. That request used one of your 250,000 free requests for the current 30 days. The Usage page shows how many you've used in the current period, and the dates it runs between.

5. Keep going