Developer FAQ

Common questions about calling the MapLark API. For plans and credits, see the pricing page. Still stuck? Contact us.

Keys and access

Can I call the API from a browser?

Not directly. API keys are secret, and CORS only allows our own apps. Call the API from your server and have your frontend call your server. The osmfeatures npm and Python packages handle the API call on the server side, and the quick start shows the call in Python, TypeScript, and cURL. Let your server choose the filters, so visitors cannot spend your key on queries of their own. Publishable browser keys are coming soon. Contact us for early access.

How do I send my API key?

In the Authorization header: Authorization: Bearer YOUR_KEY. The quick start has examples in Python, TypeScript, and cURL.

I lost my API key. Can I see it again?

No. Keys are stored hashed and shown only once, when you create them. Revoke the old key in the dashboard and create a new one. Each account has one active key. Usage is counted per account, so a new key does not reset your monthly credits.

Can I use the API from an AI assistant?

Yes. Connect Claude, Cursor, or Copilot to the hosted MCP server with your API key. Tool calls are billed to that key.

Writing queries

How do I make a query fast and cheap?

• Set type (node, way, relation) and way_shape (line or polygon). Each one narrows the search to fewer tables. See the schema page.
• Add a positive tag filter such as amenity=cafe. Tag-free and exclusion-only queries scan everything in the area.
• Send node_ids=false if you do not need way node IDs. Responses with many lines get 30 to 40% smaller, and size is part of the bill.
• Keep the area as small as the feature needs.

Which output formats are supported?

Pick one with the Accept header on /v3/osm_features:

• application/geo+json (default)
• text/csv and text/tab-separated-values
• application/flatgeobuf
• application/vnd.apache.parquet (GeoParquet)

Can I query inside a city or country boundary?

Yes. Pass within=relation/<id> (or way/<id>) instead of a bbox, with the OSM id of the boundary. Features on the boundary line are included. The same area caps as a bbox apply, so a whole country usually needs count or density instead.

How do I get one map pin for a building or park?

Add centroid=true. Every line and polygon then carries properties.centroid, a GeoJSON Point you can use as a marker. The restaurant guide example does this.

Why does a boundary relation come back twice?

Boundary relations are stored both as a line and as a polygon. Without way_shape you get both copies. Set way_shape=polygon or way_shape=line to get one.

What does limit do?

It caps the number of features returned. When more features match, the response is cut and the X-Has-More header is true. Omit it to get up to your plan's max_limit. A limit above max_limit is HTTP 400 limit_exceeds_tier.

Errors and limits

Why did I get HTTP 400 result_too_large?

More features matched than your plan's max_limit. You get an error, never a silently cut result. Narrow the query with tags, type and way_shape, or split the area into tiles. The osmfeatures packages can do the split for you (autoSplit in TypeScript, auto_split in Python). Use count first if you are unsure how many features match.

Why did I get HTTP 400 query_timeout?

The query ran longer than your plan's statement timeout. Make it more selective, using the tips under fast queries, or split the area.

What does HTTP 429 mean?

You hit one of these limits. The subtype in the error body says which:

• rate_limit_second: too many requests per second for your plan.
• concurrency_limit: too many queries running at once on your key.
• rate_limit_throttled: a free account past its monthly credits, which runs at a reduced rate until the month resets.
• free_tier_busy: all shared free-tier query slots are in use. Retry shortly.

Wait and retry with backoff. The osmfeatures packages retry for you.

Am I charged for failed requests?

Requests rejected before any query runs, such as validation errors and 429s, are free. Errors that ran SQL, such as result_too_large and query_timeout, are charged for the time they used. The body includes units and the response has an X-Usage-Units-Charged header. If you cancel a request after it has started, you pay for the work done so far.

On the Overpass endpoint (/api/interpreter), any error after the query parses is charged for its time, since earlier statements may already have run. Only parse errors and server errors are free there.

How do I check my usage?

The dashboard shows usage history and recent requests. From code, call GET /v1/usage with your key. Once your email is verified, we also email you at 75% and 100% of your monthly credits. You can turn these alerts off in your dashboard profile.

Data and licensing

Can I use the data in a commercial product?

Yes. OpenStreetMap data is licensed under the Open Database License (ODbL). Credit "© OpenStreetMap contributors" wherever you show it publicly. Maps, images, and other works made from the data only need that credit. If you publicly share a database derived from OSM data, for example OSM features merged with your own records, that database must also be offered under the ODbL. See the OSM Foundation's community guidelines for where the line falls.

Can I run my own SQL?

No. Every query goes through HTTP parameters, which keeps them fast and safe on shared hardware. The tags query language covers AND, OR, NOT, and regex. If you need joins across a whole dataset, contact us.