Developer Reference

Integrate MapFramer into your stack

Convert Google Maps short links into high-performance, coordinate-precise iframes. No Google API keys, no Google Cloud billing, just raw location power.

End-to-End Integration Roadmap

STEP 01Get Your API Key

Retrieve your unique `mf_xxxx` token from the dashboard. This identifies your project and handles rate limiting.

STEP 02Store Your Key Securely

Never use keys in client-side code. Use an environment variable like `MAPFRAMER_API_KEY` on your backend server.

STEP 03Backend Resolution

When an admin saves a map link, call our POST API. We'll resolve the short link even if it points to a dynamic coordinate pin.

STEP 04Store the Result

Save the `embedUrl` or the `iframeHtml` in your own database. Treat this resolve step as a one-time operation.

STEP 05Render Local-Speed Maps

Display the map using your stored URL. Google takes over from here—served directly from their global CDN with 0 latency.

Authentication

We use Bearer tokens for authentication. Include it in the header for secure backend calls.

Important: Calling the API from the browser will expose your token. Always implement a proxy endpoint on your backend or call it directly from your server actions.

http

Authorization: Bearer mf_your_token_here

Resolve API

POST v1/resolve

Accepts a Google Maps short link (`maps.app.goo.gl`) and returns structured location data plus a coordinate-based embed URL.

Request Body

json

{
  "url": "https://maps.app.goo.gl/55mmCVHWZFa8MT3w8"
}

Example Resolution

json

{
  "success": true,
  "data": {
    "type": "place",
    "query": "Calcutta Rowing Club (CRC)",
    "coords": { "lat": 22.564, "lng": 88.341 }
  },
  "embedUrl": "https://www.google.com/maps?q=Calcutta%20Rowing%20Club%20(CRC)%2C%2022.56%2C88.34&z=17&output=embed",
  "iframeHtml": "<iframe src='...' width='100%' height='100%' style='...' />",
  "cached": true
}

Flexible Sizing (CSS/Tailwind)

Our generated `iframeHtml` returns a production-ready embed with width: 100% and height: 100%. We include a min-height: 450px fallback.

This gives you **total functionality**: if you wrap the iframe in a parent container with a specific height, the map will fill it completely. If not, it safely defaults to a standard height.

html

<div className="w-full h-[600px] lg:h-[800px] overflow-hidden rounded-2xl">
  <!-- MapFramer iframe fills this container perfectly -->
  {iframeHtml}
</div>

Caching Layers

Server-Side Cache

MapFramer caches every resolution. If multiple customers request the same link, the response is served in <50ms from our Redis layer.

Client-Side Storage

Once you resolve a link, store it in your DB. Subsequent views on your site call Google Directly—eliminating latency and cost.

Integration (React / Next.js)

tsx

// Server Component or Action
async function GetMap(link: string) {
  const res = await fetch("https://mapframer.dev/api/v1/resolve", {
    method: "POST",
    headers: { "Authorization": `Bearer ${process.env.MF_KEY}` },
    body: JSON.stringify({ url: link })
  });
  return res.json();
}

// Frontend Component
export function MapDisplay({ iframeHtml }) {
  return (
    <div className="rounded-2xl overflow-hidden h-[450px]">
       <div dangerouslySetInnerHTML={{ __html: iframeHtml }} />
    </div>
  );
}

Frequently Asked Questions

Do I need a Google Maps API Key?

No. MapFramer operates entirely independent of your Google Cloud account. You just need a MapFramer API key, and we handle the resolution and expansion engine entirely on our side.

Is there a rate limit?

Yes, depending on your tier. The Starter tier allows up to 500 requests per month. If you exceed this, the API will return a 429 status code. For unlimited needs, please contact us for the Enterprise plan.

Are the generated iframes responsive?

Yes! By default, the generated `iframeHtml` is styled with `width: 100%` and `height: 100%`, so it will perfectly adapt to whatever container you wrap it in.

Start framing today

Ready to move beyond manual embed extraction?

Get API Token View Source