DEV Community: PlaceKit

How to use DEV.to as a CMS to make a blog with NextJS

Nicolas Torres — Thu, 11 Jan 2024 10:08:29 +0000

If you need a blog on your website, you can use DEV.to as a CMS to save a lot of time thanks to their API. Your editorial line should be tech-related though, as your articles will be published on both your website and DEV.

As PlaceKit is a tech startup, it is essential to host a blog to increase our search engines presence. Paying for a hosted CMS was not an option as we are self-funded, and self-hosting an open-source CMS would have cost us some setup and maintenance time that we'd rather allocate to more important matters. So building on top of DEV felt like a reasonable option, as we could also leverage its visibility.

We'll go through all the steps to create a blog in NextJS sourcing its articles from DEV API:

Preparing NextJS
Preparing methods
Listing articles
Article page
Updating canonical for SEO
Bonus: handling pagination

👉 See also: DEV API reference.

Don't let the article length or the number of code snippets intimidate you, I had to cover all possible implementation strategies with NextJS, using /pages or /app, SSG or SSR... 🥲

1. Preparing NextJS

Dependencies

DEV API serves articles in markdown, so we will be using Marked to parse it to HTML, and Prism for code syntax highlighting. Add them to your project:

npm install --save marked prismjs

Environment variables

Let's start with environment variables. We will need these:

# Enable articles search engines indexing
# do NOT set in development, uncomment when in production
# NEXT_PUBLIC_INDEXING=true

# Your website base URL
NEXT_PUBLIC_BASE_URL=http://localhost:3000
# NEXT_PUBLIC_BASE_URL=https://example.com

# DEV settings
DEVTO_API_KEY=<your-api-key>
DEVTO_USERNAME=<your-username>

Create an API key in your Account settings > Extensions > DEV Community API Keys.
Replace <your-api-key> in the env vars with the generated API key.
Replace <your-username> in the env vars with your DEV profile username or organization username.

⚠️ Important note: make sure the build environment for production has all these environment variables set. Sometimes we forget to add them when we're building in a CI environment like Google Cloudbuild for example.

Pages structure with `/pages` router

.
├── ...
├── pages
│   ├── ...
│   ├── blog                   # Blog route
│   │   ├── index.jsx          # Blog home page (articles list)
│   │   └── articles           # Blog articles
│   │       └── [slug].jsx     # Blog article dynamic route page
│   └── ...
└── ...

Pages structure with `/app` router

.
├── ...
├── app
│   ├── ...
│   ├── blog                   # Blog route
│   │   ├── page.jsx           # Blog home page (articles list)
│   │   └── articles           # Blog articles
│   │       └── [slug]         # Blog article dynamic route
│   │           └── page.jsx   # Blog article page
│   └── ...
└── ...

2. Preparing Methods

We're writing all our DEV API calls as reusable functions that will be common to all NextJS strategies, and prevent some bulk in your component pages.

I personnally like to put them in a utils folder, but you're free to place them wherever you want to. For the convenience of this tutorial, I'll place those helpers in ./utils/blog-methods.js and import them using the default absolute path alias @/utils/blog-methods.js.

// /utils/blog-methods.js
import { marked } from 'marked';

// fetch all articles, looping through the paginated DEV API route
export const getAllArticles = async (fetchOptions) => {
  let articles = [];

  // URL for user articles
  const url = new URL(`https://dev.to/api/articles/${process.env.DEVTO_USERNAME}/all`);
  // URL for organization articles
  // const url = new URL(`https://dev.to/api/organizations/${process.env.DEVTO_USERNAME}/articles`);

  // set default query parameters
  url.searchParams.set('page', 1);
  url.searchParams.set('per_page', 10);
  do {
    // fetch current page articles
    const res = await fetch(url, {
      ...fetchOptions,
      headers: {
        ...fetchOptions?.headers,
        'api-key': process.env.DEVTO_API_KEY,
      },
    });

    // stop looping on empty response
    if (!res.ok) {
      throw Error('Failed to fetch articles');
    }
    const data = await res.json();
    if (!data?.length) {
      break;
    }

    // store fetched articles
    articles = articles.concat(data);

    // increment page query parameter
    url.searchParams.set('page', +url.searchParams.get('page') + 1);
  } while (true);

  // return all articles
  return articles;
};

// fetch article by slug
export async function getArticleBySlug(slug, fetchOptions) {
  const res = await fetch(`https://dev.to/api/articles/${process.env.DEVTO_USERNAME}/${slug}`, {
    ...fetchOptions,
    headers: {
      ...fetchOptions?.headers,
      'api-key': process.env.DEVTO_API_KEY,
    },
  });
  if (!res.ok) {
    return null;
  }
  const data = await res.json();

  // convert markdown to HTML
  data.html = marked.parse(data.body_markdown);
  return data;
}

3. Listing articles

In our first version, we are focusing on retrieving and showing all articles on the same page. Depending on your NextJS strategy, you will need to call getAllArticles accordingly:

`/pages` router

// /pages/blog/index.jsx
import { getAllArticles } from '@/utils/blog-methods.js';

export default function BlogHome({ articles }) {
  // your page template
  return (
    /* ... */
  );
}

// To generate at build time (SSG), use `getStaticProps`
// To render at request time (SSR), use `getServerSideProps` instead
export async function getStaticProps() {
  const articles = await getAllArticles();
  return {
    props: {
      articles,
    },
  };
}

SSR with getServerSideProps in /pages router is not recommended because it won't cache the HTTP call, and therefore call DEV API each time a visitor opens the page.

`/app` router

// /app/blog/page.jsx
import { getAllArticles } from '@/utils/blog-methods.js';

export default async function Page() {
  // fetch data
  const articles = await getAllArticles({
    cache: 'force-cache', // set 'no-store' to always fetch at request time
    next: { revalidate: 24 * 60 * 60 * 1000 }, // revalidate cache every day
  });

  // your page template
  return (
    /* ... */
  );
}

Link articles

You now have access to the articles arrays within your page component, with a lot of details to display their title, description, tags, date and some other metadata. See the full JSON response to get the exhaustive list of available properties.

To link an article from the blog home, simply use href={`/blog/articles/${article.slug}`}:

// /pages/blog/index.jsx OR /app/blog/page.jsx
import Link from 'next/link';
// ...
export default function BlogHome({ articles }) {
  // ...
  return (
    <ul>
      {articles?.map((article) => {
        return (
          <li key={article.id.toString()}>
            <Link href={`/blog/articles/${article.slug}`}>{article.title}</Link>
          </li>
        );
      })}
    </ul>
  );
}
// ...

4. Article page

Again, depending on the NextJS strategy, we'll load the article and handle 404s in different ways. The main difference with the blog home page here is that in SSG/ISG mode, we need to tell NextJS all the pages that it has to generate.

`/pages` router, SSR mode

// /pages/blog/article/[slug].jsx
import { getArticleBySlug } from '@/utils/blog-methods.js';

// Article page component
export default function BlogArticle({ article }) {
  return <div dangerouslySetInnerHTML={{ __html: article.html }} />;
}

// Fetch article data at request time and inject as page props
export async function getServerSideProps({ params }) {
  const article = await getArticleBySlug(params.slug);
  return !article
    ? { notFound: true } // show 404 if fetching article fails
    : {
        props: {
          article,
        },
      };
}

`/pages` router, SSG mode

// /pages/blog/article/[slug].jsx
import { getAllArticles, getArticleBySlug } from '@/utils/blog-methods.js';

// Article page component
export default function BlogArticle({ article }) {
  return <div dangerouslySetInnerHTML={{ __html: article.html }} />;
}

// Pregenerate all article pages in SSG
export async function getStaticPaths() {
  const articles = await getAllArticles();
  const paths = articles.map(({ slug }) => ({ params: { slug } }));
  return {
    paths,
    fallback: false, // show 404 if not on the articles list
  };
}

// Fetch article data at build time and inject as page props
export async function getStaticProps({ params }) {
  const article = await getArticleBySlug(params.slug);
  if (article === null) {
    throw Error(`Failed to fetch article ${params.slug}`);
  }
  return {
    props: {
      article,
    },
  };
}

`/app` router

// /app/blog/article/[slug]/page.jsx

import { notFound } from 'next/navigation';
import { getArticleBySlug, getAllArticles } from '@/utils/blog-methods.js';

const cacheParams = {
  cache: 'force-cache', // set 'no-store' to always fetch at request time
  next: { revalidate: 24 * 60 * 60 * 1000 }, // revalidate cache every day
};

// Article page component
export default async function Page({ params }) {
  // Fetch article data at request time
  const article = await getArticleBySlug(params.slug, { cache: 'no-store' });

  if (!article) {
    notFound(); // show 404 if fetching article fails
  }

  return <div dangerouslySetInnerHTML={{ __html: article.html }} />;
}

// (Optional) Pregenerate all article pages at build time
export async function generateStaticParams() {
  const articles = await getAllArticles(cacheParams);
  return articles.map(({ slug }) => ({ slug }));
}

Adding anchors and code snippets syntax highlighting

Finally, let's update our utils/blog-methods.js file to configure Prism and Marked to add heading anchors and code syntax highlighting:

// /utils/blog-methods.js
import { marked } from 'marked';
import Prism from 'prismjs';

// load only languages you use
import 'prismjs/components/prism-bash';
import 'prismjs/components/prism-css';
import 'prismjs/components/prism-javascript';
import 'prismjs/components/prism-jsx';
import 'prismjs/components/prism-json';
import 'prismjs/components/prism-markup-templating';
import 'prismjs/components/prism-markdown';

// we handle Prism highlighting manually
Prism.manual = true;

// marked options
marked.use({
  breaks: true,
  gfm: true,
  extensions: [
    {
      // syntax highlighting on `<code>`
      // defaults to `plain` if the language isn't imported
      name: 'code',
      renderer({ lang, text }) {
        const output =
          lang in Prism.languages
            ? Prism.highlight(text.trim(), Prism.languages[lang], lang)
            : text.trim();
        const syntax = lang in Prism.languages ? lang : 'plain';
        return `<pre><code class="language-${syntax}">${output}</code></pre>`;
      },
    },
    {
      // adding heading anchors
      // same ID syntax as DEV so we don't need to rewrite links href
      name: 'heading',
      renderer({ text, depth }) {
        const id = text
          .toLocaleLowerCase()
          .replace(/[^\w\s]/g, '')
          .trim()
          .replace(/\s/g, '-');
        return `<h${depth}><a name="${id}" href="#${id}"></a>${text}</h${depth}>`;
      },
    },
  ],
});

// ...

And then import the CSS file for your prefered Prism theme in your article page:

// /pages/blog/article/[slug].jsx or /app/blog/article/[slug]/page.jsx
import 'prismjs/themes/prism.css'; // default theme

5. Updating canonical for SEO

Google and other search engine don't like much duplicate content, and will penalize your referencing if you simply post the same article on both DEV and your website.

To avoid this, we make use of the canonical URL, telling the search engines that the original post is in our website, and that DEV is a legitimate duplicate. So your website will rank articles in priority.

Make sure NEXT_PUBLIC_INDEXING is not set in development, and set to true in production, because we will update the DEV article canonical value with the public article URL. We create a new helper updateArticleCanonical and call it from the getArticleBySlug helper like so:

// /utils/blog-methods.js
// ...

// fetch article by slug
export async function getArticleBySlug(slug, fetchOptions) {
  /* ... */

  // update canonical on DEV
  await updateArticleCanonical(data);
  return data;
}

// update canonical URL when it goes public only if it isn't already set
async function updateArticleCanonical(article) {
  if (
    process.env.NEXT_PUBLIC_INDEXING &&
    !article.canonical_url.startsWith(process.env.NEXT_PUBLIC_BASE_URL)
  ) {
    const canonical = new URL(`/blog/articles/${article.slug}`, process.env.NEXT_PUBLIC_BASE_URL);
    await fetch(`https://dev.to/api/articles/${article.id}`, {
      method: 'PUT',
      body: JSON.stringify({
        article: {
          canonical_url: canonical.href,
          tags: article.tags, // for some reason, if not set, tags will be erased
        },
      }),
    });
  }
}

On a side note, we use next-sitemap to automatically generate a sitemap.xml, and our blog generated pages are processed without any specific config.

6. Bonus: handling pagination

Handling pagination in the blog home page is a matter of playing with NextJS router optional catch-all feature, like we did for prerendering individual articles at build time.

We could also use simple dynamic routes like /pages/blog/pages/[page].jsx and redirect /blog to /blog/page/1 in next.config.js, but I find it more elegant to use /blog and /blog/page/2, and the examples will be more exhaustive that way, for you to be able to choose what you prefer.

So let's add a redirect entry in our next.config.js for /blog/page/1 to be redirected permanently to /blog:

const nextConfig = {
  // ...
  async redirects() {
    return [
      {
        source: '/blog/page/1',
        destination: '/blog',
        permanent: true,
      },
    ];
  },
};

module.exports = nextConfig;

We still then need to load all articles with our getAllArticles helper from DEV to tell Next how many pages it will have to generate.

Folder structure

Let's first rename /pages/blog/index.jsx to /pages/blog/[[...page]].jsx, or /app/blog/page.jsx to /app/blog/[[...page]]/page.jsx to be able to catch both /blog, /blog/page/2, etc.

Careful that now, with that optional paramater, /blog/invalid/path will also be caught, so we need to control what paths we allow and show a 404 for the others.

Adding pagination data to articles list

We're wrapping getAllArticles to add some pagination data that will be common to all Next strategies:

// /utils/blog-methods.js
// ...

export const articlesPerPage = 10;

// fetch all articles with pagination
// careful, page query param is a 1-based integer for URL display
export async function getArticlesAtPage(params, fetchOptions) {
  const allArticles = await getAllArticles(fetchOptions);
  const pageParam = Number(params.page?.[1] || '1'); // 1-based
  const currentPage = Math.max(0, pageParam - 1); // 0-based for computations
  const start = currentPage * articlesPerPage;
  const end = start + articlesPerPage;
  return {
    articles: allArticles.slice(start, end),
    currentPage: currentPage + 1, // 1-based for display
    nbPages: Math.ceil(allArticles.length / articlesPerPage),
    perPage: articlesPerPage,
    nbArticles: allArticles.length,
  };
}

`/pages` router, SSR mode

// /pages/blog/index.jsx

import { getArticlesAtPage } from '@/utils/blog-methods.js';

//...

export async function getServerSideProps({ params }) {
  const pageProps = await getArticlesAtPage(params);
  return !pageProps.articles.length
    ? { notFound: true }
    : {
        props: pageProps, // { articles, currentPage, nbPages, ... }
      };
}

`/pages` router, SSG mode

// /pages/blog/index.jsx

import { getAllArticles, getArticlesAtPage, articlesPerPage } from '@/utils/blog-methods.js';

// ...

export async function getStaticPaths() {
  // fetching all articles here to compute the total number of pages
  const allArticles = await getAllArticles();
  const nbPages = Math.ceil(allArticles.length / articlesPerPage);
  const pages = Array.from(Array(nbPages).keys()); // [0,1,...,N-1]
  const paths = pages.map((n) => ({
    params: {
      page:
        n === 0
          ? null // `/blog`
          : ['page', `${n + 1}`], // pages [2,3,...,N]
    },
  }));
  return {
    paths,
    fallback: false, // show 404 if not on the pages list
  };
}

export async function getStaticProps({ params }) {
  const pageProps = await getArticlesAtPage(params);
  return {
    props: pageProps, // { articles, currentPage, nbPages, ... }
  };
}

`/app` router

// /app/blog/page.jsx
import { notFound } from 'next/navigation';
import { getAllArticles, getArticlesAtPage, articlesPerPage } from '@/utils/blog-methods.js';

// ...

const cacheParams = {
  cache: 'force-cache', // set 'no-store' to always fetch at request time
  next: { revalidate: 24 * 60 * 60 * 1000 }, // revalidate cache every day
};

export default async function Page({ params }) {
  const pageProps = await getArticlesAtPage(params, cacheParams);

  if (!pageProps.articles?.length) {
    notFound();
  }

  // your page template
  return {
    /* ... */
  };
}

// (Optional) Pregenerate all article pages at build time
export async function generateStaticParams() {
  const articles = await getAllArticles(cacheParams);
  const nbPages = Math.ceil(articles.length / articlesPerPage);
  const pages = Array.from(Array(nbPages).keys()); // [0,1,...,N-1]
  return pages.map((n) => ({
    page:
      n === 0
        ? null // `/blog`
        : ['page', `${n + 1}`], // pages [2,3,...,N]
  }));
}

Check out our blog at placekit.io/blog for a live implementation example (and more articles 👀).

We hope this tutorial helped you setting up DEV as a CMS for your own NextJS website!

Google Maps is always right… right?

Raphaël Daguenet — Wed, 22 Nov 2023 13:07:51 +0000

For developers dealing with geographic information systems, Google Maps represents the industry standard. When you're working on crafting a competing solution, benchmarking against this giant is a logical and necessary step.

We recently integrated a new country-state boundary functionality into our PlaceKit API. To estimate performance, we tested our system against the Google Maps API and encountered unexpected anomalies. A manual review of each discrepancy led to an interesting discovery: we traced all anomalies back to Google Maps, offering a glimpse into its occasionally flawed calculations.

tl;dr: Google Maps showed a 0.006% error rate over 1,000,000 tests, with errors spanning thousands of miles.

A bit of context
Navigating state boundaries
Not so close to a state boundary
The Wild Turkey Run
Off-course: far beyond state boundaries
An interstate flight is cheaper than Google Maps API pricing ✈️
Lost in address translation

A bit of context

A customer required precise geolocation capabilities to determine their users' current country and state at a centimeter/inch precision. This process, known as reverse geocoding, involves submitting geographic coordinates (e.g. 37.768991,-122.475353) to an API, which then returns the corresponding location data:

{ state: "California", country: "USA" }

To ensure accuracy and scalability for our new API, we conducted a comparative analysis against Google Maps API as our validation metric. We compared the state and country data returned by both APIs for the same latitude and longitude coordinates.

Out of 1,000,000 tests conducted, we encountered 60 failures, instances where Google Maps and our API diverged on the state or country returned.

In most cases, this error rate is totally acceptable and insignificant compared to the quality of the overall Google Maps products. Yet, in certain industries like online gambling or specific e-commerce items, the legislation is very strict making data accuracy crucial for business viability (e.g. get the user geolocation for an online casino app).

Legality of gambling types per US states (wikipedia)

For each of these failed tests, we manually investigated which API was wrong and why.
In all 60 tests, it was discovered that Google Maps was incorrect.

To perform those tests, we used Google Maps and PlaceKit reverse-geocoding endpoints, comparing administrative_area_level_1 / administrative and country attributes. For clarity, red pins on screenshots mark the coordinates used for the tests.

👉 Checkout Google Maps API responses using the links provided under each screenshot.

Let's dive in a few examples.

Navigating state boundaries

👉 Google Maps API response & Google Maps UI

Coordinates   📍 39.719947,-77.505964
Google        ❌ Maryland
PlaceKit      ✅ Pennsylvania
Error dist.   ⚠️ 5m - 16ft

The map clearly illustrates the demarcation of state lines with our coordinates pinpointed accurately. The Google Maps interface displays the correct location —yet, the Google Maps API returns a mismatched state only meters away.

Because the house is spanning over two states, the first result of type street_address from the API is pointing to the closest street, placing it inaccurately in Maryland. We also notice that Google Maps UI uses this erroneous record.

Adding a filter result_types=administrative_area_level_1 to the request yields the correct state. However, as a developper using a reverse-geocoding API, results are misleading as you are expecting the first result to be on the exact coordinates and not snapping to the nearest street. The goal is to identify the state associated with the coordinates provided, not a postal address to send them Black Friday gifts.

Enough nitpicking, let’s see how far this can go.

Not so close to a state boundary

👉 Google Maps API response & Google Maps UI

Coordinates   📍 30.30439,-93.74216
Google        ❌ Texas
PlaceKit      ✅ Louisiana
Error dist.   ⚠️ 167m - 548ft

In this scenario, the coordinates fall within Louisiana's borders, yet the Google Maps API erroneously identifies the location as Texas.

In reverse geocoding queries, the first result might be an interpolation, potentially deviating from the developers' expectations.

While not directly Google's fault, it can be misleading for developers assuming the first result is the most accurate and should directly match the coordinates provided. This could be considered a user experience issue with the API. Developers who don’t take this into consideration could introduce errors into their applications.

Key Takeaway: When extracting state or other attributes for a given set of coordinates, don't blindly use the first result as it might not be what you expect. Instead, add a search param political or administrative_area_level_1 to get the exact state the coordinates are in, and avoid the trap of street interpolation.

Did you notice the conflicting information in the screenshots above? The formatted address mentions "Orange, Texas 77632, USA" while Plus Code indicates "8735+Q54 Starks, Louisiana, USA".

Could Plus Codes offer a better accuracy? Let's explore this possibility.

The Wild Turkey Run

Fort Campbell is a military base located across Kentucky and Tennessee. According to Wikipedia:

While the headquarters and a great majority of the base's acreage was in Tennessee, the base's post office was in Kentucky. After many months of mail delivery problems, Colonel Guy W. Chipman requested that the address be changed to Camp Campbell, Kentucky. The War Department officially changed the address on September 23, 1942.

Alright fair enough, but we still want to know in which state are the coordinates, no matter what the postal address is. Gimme gimme the state!

👉 Google Maps API response & Google Maps UI

Coordinates   📍 36.60434,-87.46664
Google        ❌ Kentucky
PlaceKit      ✅ Tennessee
Error dist.   ⚠️ 4km - 2.5mi

The query returns an address on "Wild Turkey Run, Fort Campbell, TN 42223, United States," situated in Tennessee. However, Plus Code "JG3M+M8 Fort Campbell, Kentucky, USA" points to Kentucky.

This is confusing. Technically, the coordinates are in Tennessee, but the Plus Code introduces confusion by indicating Kentucky while the street_address provides the wrong postal state according to the military chief. Earlier in this post we assumed that since Plus Codes are founded on pure geographic coordinates without reliance on street data it would would help us avoid such errors. Here it misleads by several miles… Is there any accurate way to get the correct geographic state?

Interacting with the map, random locations around the base yield different states, snip-snap, snip-snap.

Is this example just odd because of the military base scenario? Let’s check out on civil grounds.

Off-course: far beyond state boundaries

👉 Google Maps API response & Google Maps UI

Coordinates   📍 35.07361,-85.24068
Google        ❌ Georgia
PlaceKit      ✅ Tennessee
Error dist.   ⚠️ 10km - 6mi

This one is just wrong. The API returns the address "3307 Alabama Hwy, Chattanooga, GA 30165, USA" whereas there is no Alabama Highway in Chattanooga and anyway, Chattanooga is in Tennessee. The closest Georgia boundary point is 10km / 6 miles away!

Digging on this odd result, we found that "3306 Alabama Hwy" is at the very end of the highway, which is set in Tennessee state, 20km - 13 miles away from the given coordinates.

Google Maps UI

This anomaly looks like an interpolation error by Google’s geocoder, suggesting that their system could extend a road improperly into another state.

Note: what is street number interpolation?

It's a method used to guess the location when a precise match is not available in the database. Let's say we have the data for 3305 and 3309 but a user searches for 3307. We can either return a no result (strict address validation) or estimate that 3307 is probably equidistant between 3305 and 3309 and compute the coordinates based of these two data points. Seems simple at first, but you have to consider the physical geometry of the road (not always a straight highway), terrain elevation, varying street number conventions across countries, etc.

Let’s be clear: in this scenario, we didn’t perform a forward geocoding query — give me the coordinates for "3307 Alabama Hwy, Chattanooga, GA 30165, USA". We performed a reverse geocoding query — give me the street name for coordinates 35.07361,-85.24068. Street number interpolation should not have kicked in, and should not have returned a result miles away.

We would expect a reverse geocoding request to accurately pinpoint the state corresponding to specific coordinates, rather than approximating it based on nearby street numbers.

Key Insights:

Our initial assumption about snapping to the closest known street for given coordinates is incorrect.
Our second assumption about Google Maps using the first result of the API is also inaccurate.
Google Maps does not directly use the reverse API or might apply additional post-processing to the data obtained.

An interstate flight is cheaper than Google Maps API pricing ✈️

👉 Google Maps API response & Google Maps UI

Coordinates   📍 41.83021,-87.62679
Google        ❌ Utah
PlaceKit      ✅ Illinois
Error dist.   ⚠️ 2000km - 1260mi
Round trip    ✈️ 109€ - $118

How can a reverse geocoding query be thousands of miles off?

Let's zoom in 41.83021,-87.62679 and the returned corresponding address "3520 S State St, Salt Lake City, Utah 84115, USA", despite the true location being Chicago in Illinois.

Using Google Maps directly with these coordinates takes us to the correct place in Chicago, however, the API response tells a completely different story.

Chicago, via 41.83021,-87.62679

Salt Lake City via the returned address

Can you spot the pattern in the screenshots above?

41.83021,-87.62679 points to the building 3520 which closest street is "S State St". Whereas the first API result is "3520 S State St, Salt Lake City, Utah 84115, USA".

For an unknown reason, it mixes up neighborhood information from Chicago with the locality and administrative level data from Utah — an erratic merging of geographic data that disregards the actual provided coordinates:

{
  "neighborhood": "Park Boulevard",            // ❌ in Salt Lake, ✅ in Chicago
  "locality": "Salt Lake City",                // ❌ 
  "administrative_area_level_1": "Utah",       // ❌
  "administrative_area_level_2": "Cook County" // ✅
}

It appears that the API might be following this process:

Takes the coordinates and identifies the nearest building + street address.
Performs a textual best match query across its datasets.
Returns the first record, mixing up the fields from different locations.

Shifting the coordinates slightly away from the problematic building number yields accurate results in Chicago. Attempts to duplicate this issue with address numbers common to both cities did not reproduce the same mistake.

This case highlights a unique flaw where the API logic appears to disregard the geographic context in favor of the closest textual match in their database, causing a severe drift in expectations.

Lost in address translation

👉 Google Maps API response & Google Maps UI

Coordinates   📍 29.67213,-95.27028
Google        ❌ GA
PlaceKit      ✅ Texas
Error dist.   ⚠️ 1100km - 700mi
Flight time   ✈️ 1h50

As in the previous example, the street number and street name matches exactly in another state. The coordinates are located in Houston, Texas, but the API astonishingly returns an address in Georgia, a distance of about 1100 kilometers (700 miles) away. It seems like the mail sent to this particular Houston address might encounter some logistical issues.

We identified another inconsistency in the way Google Maps API handles state names:

{
    "long_name": "GA",
    "short_name": "GA",
    "types": [
        "administrative_area_level_1",
        "political"
    ]
}

Here, the API improperly cites GA as the long_name for the administrative area level 1—where it should be the full name, Georgia. While it's a relatively minor error and easy to resolve, it could cause complications if a system relies on the full state name for an exact match.

Developers using geocoders must be aware of potential data anomalies and plan accordingly to ensure accurate results, especially when handling critical applications like package deliveries.

Wrapping up: navigating through imperfect data

What can we learn from these tests?

Google Maps !== Google Maps API —what you see on Google Maps is not what you will get via their API. And Plus-Codes seems to be using a different dataset, sometimes contradicting itself in the same record.

Our test suite is mainly located in the US but we can extrapolate that the errors detected are also present worldwide. We’ve only tested the accuracy at a high level (state), who knows what could be found by running tests at street level?

Geographic Information System (GIS) is hard work. It’s impossible to get it 100% right. While Google Maps remains a powerful and widely-used tool, these examples serve as a reminder that all geocoders have their shortcomings. From minor inaccuracies along state boundaries to significant misdirections covering thousands of miles, these are not just theoretical errors—they can have real-world implications, potentially impacting businesses applications where location accuracy is key.

Our new country-state boundaries API is available on demand. PlaceKit offers a cost-effective geocoding API with 10k free requests per month and pay-per-request pricing.

Introducing Live Patching

Nicolas Torres — Tue, 11 Jul 2023 04:51:43 +0000

Live Patching empowers you to add or fix locations on the fly with PlaceKit, and make them instantly available to your users.

Motivation

Geocoding is providing geographical coordinates corresponding to a location, and reverse geocoding means finding a location based on geographical coordinates. One common use-case of geocoding you may have seen is an address autocomplete field:

Providing geocoding services means keeping up to date a catalog of worldwide locations with their coordinates, and providing the API to browse through that immense amount of data. The catalog is an overly tedious task, which always requires some degree of automation and approximation. Thus no one, not even Google Maps, can pretend to have it 100% accurate.

When we were working on Algolia Places (before it got sunset), we noticed a critical pain point for our customers. Some use cases need a way to fix locations from a catalog, without delay. For example, an e-commerce website experiencing mis-shipments due to an invalid address will often reach out to its user to get the correct one, and need a way to fix it once and for all to prevent any more failed delivery for that person. And that would occur multiple times per week.

Even if we were somewhat reactive in fixing locations at Algolia Places, it had to go through a submission process via a form, manually reviewing internally whenever the product team has the time. It's very time-consuming and a bit hard to propagate fixes in a large automated pipeline processing. The same goes with our competitors like Google Places or Mapbox: at best, fixing a location is manual a process that could take days or weeks of back-and-forth validation.

At PlaceKit, we believe businesses know better, so we're introducing a differentiating feature: Live Patching, to let you add missing locations or fix existing ones without delay, providing the best experience possible for your users.

Instead of waiting for your favorite geocoding service employees to review and validate/reject your submission, PlaceKit enables you to build your own validation flow. You can either create fixes directly from the dashboard or API, or review and validate suggestions coming from your users. Once you approved the changes, the patches are instantly available to all your end users.

How does it work

We merge your published patches in the autocomplete suggestions at search time, only for your applications:

For missing locations, we append them to the search, and it goes through the same relevance algorithm as any other location from our catalog.
For fixes, we detect and substitute them from our original record, so there are no duplicates in the suggestions list.

Patches are tied to your PlaceKit account, so they're shared across all your applications, but not shared with other PlaceKit customers: only your users see your fixes.

Using the admin panel

Sign in to your PlaceKit account and navigate to the new "Patch" tab. You should see an empty list and an "Add patch" button. Click on it to access the form. For example, adding a new street named "New Street" to Tahoe City:

When adding a missing location, you can pre-fill the form with an existing location. For example, if you're adding a missing street, that could come in handy to fill in all the city information.

When fixing an existing location, it'll be required that you search for the existing location first. It'll fill the form for you, and then you only have to fix the wrong fields.

You can publish and unpublish it at any time. Published means your users will see it when they search for a location; unpublished means it's only showing on your Patch page on the admin panel.

Now you have it ready for your users in the autocomplete:

Using the API

We've updated our API Reference and the JS Client with the new endpoints.

⚠️ You need to use a private API key from any of your apps.

Snippets below showcase both cURL and JavaScript implementations. Before running the JS examples, instantiate PlaceKit Client:

// CommonJS syntax:
const placekit = require('@placekit/client-js');

// ES6 Modules syntax:
import placekit from '@placekit/client-js';

const pk = placekit('<your-api-key>');

Now let's make a tour of the feature:

Adding a missing location

const result = await pk.patch.create({
 type: 'street',
 name: 'New street',
 city: 'Tahoe City',
 county: 'Placer County',
 administrative: 'California',
 country: 'United States of America',
 countrycode: 'us',
 coordinates: '39.1689372,-120.1434787',
 zipcode: ['96154'],
 population: 2644
});

curl -l -X POST 'https://api.placekit.co/patch' \
 -H 'x-placekit-api-key: <your-api-key>' \
 -H 'Content-Type: application/json' \
 -d '{"record":{"type":"street","name":"New street","city":"Tahoe City","county":"Placer County","administrative":"California","country":"United States of America","countrycode":"us","coordinates":"39.1689372,-120.1434787","zipcode":["96154"],"population":2644}}'

Fixing an existing location

// Search for an existing record first
const { results } = await pk.search('Los Angeles', {
 types: ['city'],
 countries: ['us'],
});

// Fix the existing record
await pk.patch.create(
 { zipcode: ['96154'] },
 { status: 'approved' },
 results[0], // original record
);

curl -l -X PUT 'https://api.placekit.co/patch' \
 -H 'x-placekit-api-key: <your-api-key>' \
 -H 'Content-Type: application/json' \
 -d '{"update":{"zipcode":["96154"]},"origin":{/* original record */},"status":"approved"}'

Listing patch records

// Get all patches, paginated
const { results } = await pk.patch.list();

// Filter and paginate patches
const { results } = await pk.patch.list({
 query: 'new',
 countries: ['us'],
 types: ['street'],
 status: 'approved',
 maxResults: 10,
 offset: 0,
});

# Get all patches, paginated
curl -l -X POST 'https://api.placekit.co/patch/search' \
 -H 'x-placekit-api-key: <your-api-key>'

# Filter and paginate patches
curl -l -X POST 'https://api.placekit.co/patch/search' \
 -H 'x-placekit-api-key: <your-api-key>' \
 -H 'Content-Type: application/json' \
 -d '{"query":"new","countries":["us"],"status":"approved","maxResults":10,"offset":0}'

Retrieving a patch record

// Retrieve default language
const result = await pk.patch.get('<patch-id>');

// Retrieve translation
const result = await pk.patch.get('<patch-id>', 'fr');

# retrieve default language
curl -l -X GET 'https://api.placekit.co/patch/<patch-id>' \
 -H 'x-placekit-api-key: <your-api-key>'

# retrieve translation
curl -l -X GET 'https://api.placekit.co/patch/<patch-id>?language=fr' \
 -H 'x-placekit-api-key: <your-api-key>'

Updating a patch record

// Update and publish
const result = await pk.patch.update(
 '<patch-id>',
 { coordinates: '39.1689372,-120.1434787' },
 { status: 'approved' }
);

// Update translation
const result = await pk.patch.update(
 '<patch-id>',
 { name: 'Rue Nouvelle' }, 
 { language: 'fr' }
);

// Unpublish
const result = await pk.patch.update(
 '<patch-id>',
 undefined,
 { status: "pending" }
);

# Update and publish
curl -l -X PATCH 'https://api.placekit.co/patch/<patch-id>' \
 -H 'x-placekit-api-key: <your-api-key>' \
 -H 'Content-Type: application/json' \
 -d '{"update":{"coordinates":"39.1689372,-120.1434787"},"status":"approved"}'

# Update translation
curl -l -X PATCH 'https://api.placekit.co/patch/<patch-id>' \
 -H 'x-placekit-api-key: <your-api-key>' \
 -H 'Content-Type: application/json' \
 -d '{"update":{"name":"Rue Nouvelle"},"language":"fr"}'

# Unpublish
curl -l -X PATCH 'https://api.placekit.co/patch/<patch-id>' \
 -H 'x-placekit-api-key: <your-api-key>' \
 -H 'Content-Type: application/json' \
 -d '{"status":"pending"}'

Delete a patch record

// Delete translation
await pk.patch.deleteLang('<patch-id>', 'fr');

// Delete patch record
await pk.patch.delete('<patch-id>');

# Delete translation
curl -l -X DELETE 'https://api.placekit.co/patch/<patch-id>/language/fr'

# Delete patch
curl -l -X DELETE 'https://api.placekit.co/patch/<patch-id>'

It's mostly just a developer feature for now, but stay tuned, we'll add more to it soon. Nonetheless, we're excited to bring this unique feature to our service, and can't wait to see your implementations!

Making React-Leaflet work with NextJS

Nicolas Torres — Fri, 23 Jun 2023 08:55:10 +0000

I've ran into some issues implementing React Leaflet with NextJS for our admin panel at PlaceKit. So let's gather my findings into a single article, hoping it'll save you some time.

Because NextJS has an SSR (server-side rendering) layer, importing third-party front-end libraries sometimes results in headaches.

Most of the time, you just have to wrap your front-end component with next/dynamic to make it lazy load, making the SSR pass simply ignore it:

// MyComponent.jsx
import frontLib from '<your-front-end-library>';
const MyComponent = (props) => {
  // do something with frontLib
};
export default MyLazyComponent;


// MyPage.jsx
import dynamic from 'next/dynamic';

const MyComponent = dynamic(
  () => import('./MyComponent'),
  {
    ssr: false,
    loading: () => (<div>loading...</div>),
  }
);

const MyPage = (props) => (
  <MyComponent />
);

But in the case of React Leaflet, you may need to put in some more efforts.

Passing `ref`

If you simply assign a ref to lazy-loaded <MapContainer>, you'll get a unusable proxy reference coming from dynamic:

// Map.jsx
import dynamic from 'next/dynamic';
import { useEffect, useRef } from 'react';

const MapContainer = dynamic(
  () => import('react-leaflet').then((m) => m.MapContainer),
  { ssr: false }
);

const Map = (props) => {
  const mapRef = useRef(null);
  useEffect(
   () => console.log(mapRef.current), // { retry: fn, ... }
   [mapRef.current]
  );
  return (
    <MapContainer ref={mapRef} ?>
  );
};

export default Map;

The trick is a bit bulky, but you have to wrap it under another component and forward the ref as a standard property (mapRef here), and you lazy load that one instead:

// MapLazyComponents.jsx
import {
  MapContainer as LMapContainer,
} from 'react-leaflet';

export const MapContainer = ({ forwardedRef, ...props }) => (
  <LMapContainer {...props} ref={forwardedRef} />
);

// Map.jsx
import dynamic from 'next/dynamic';
import { forwardRef, useEffect, useRef } from 'react';

const LazyMapContainer = dynamic(
  () => import('./MapLazyComponents').then((m) => m.MapContainer),
  { ssr: false }
);

const MapContainer = forwardRef((props, ref) => (
  <LazyMapContainer {...props} forwardedRef={ref} />
));

const Map = (props) => {
  const mapRef = useRef(null);
  useEffect(
   () => console.log(mapRef.current), // this works!
   [mapRef.current]
  );
  return (
    <MapContainer ref={mapRef} />
  );
};

export default Map;

Organizing your components

As we'll be preparing a few other React Leaflet components in the following examples, let's reorganise this into 3 files:

Map.jsx: your final component or page showing the map.
MapComponents.jsx: components that will lazy-load the React Leaflet ones. These will be ready to import as-is.
MapLazyComponents.jsx: wrappers that forward ref or are using front-end specific features, to be lazy-loaded by MapComponents.jsx.

Let's also add <TileLayer> and <ZoomControl> as we won't need any specific changes apart from loading them with dynamic.

So at this point you get:

// MapLazyComponents.jsx
import {
  MapContainer as LMapContainer,
} from 'react-leaflet';

export const MapContainer = ({ forwardedRef, ...props }) => (
  <LMapContainer {...props} ref={forwardedRef} />
);


// MapComponents.jsx
import dynamic from 'next/dynamic';
import { forwardRef } from 'react';

export const LazyMapContainer = dynamic(
  () => import('./MapLazyComponents').then((m) => m.MapContainer),
  {
    ssr: false,
    loading: () => (<div style={{ height: '400px' }} />),
  }
);
export const MapContainer = forwardRef((props, ref) => (
  <LazyMapContainer {...props} forwardedRef={ref} />
));

// direct import from 'react-leaflet'
export const TileLayer = dynamic(
  () => import('react-leaflet').then((m) => m.TileLayer),
  { ssr: false }
);
export const ZoomControl = dynamic(
  () => import('react-leaflet').then((m) => m.ZoomControl),
  { ssr: false }
);


// Map.jsx
import { useEffect, useRef } from 'react';

// import and use components as usual
import { MapContainer, TileLayer, ZoomControl } from './MapComponents.jsx';

const Map = (props) => {
  const mapRef = useRef(null);
  return (
    <MapContainer
      ref={mapRef}
      touchZoom={false}
      zoomControl={false}
      style={{ height: '400px', zIndex: '0!important' }}
    >
      <TileLayer url="..." attribution="..." style={{ zIndex: '0!important' }} />
      <ZoomControl position="topright" style={{ zIndex: '10!important' }} />
    </MapContainer>
  );
};

export default Map;

Using custom Marker icons

Alright, now that we start having a Map, let's add a marker. But most of the time you'd want to use a custom icon with it.

Custom Marker icons need to use L.Icon() from leaflet itself, which is a library instantiating stuff in window, so it breaks SSR when importing in Next. But it can not be loaded with dynamic() or even with React.lazy() which are exclusive to lazy loading components.

So, let's wrap our <Marker> component in MapLazyComponents.jsx as it'll be depending on front-end exclusive features:

// MapLazyComponents.jsx
import { useEffect, useState } from 'react';
import {
  MapContainer as LMapContainer,
  Marker as LMarker,
} from 'react-leaflet';

// ...
export const Marker = ({ forwardedRef, icon: iconProps, ...props }) => {
  const [icon, setIcon] = useState();

  useEffect(
    () => {
      // loading 'leaflet' dynamically when the component mounts
      const loadIcon = async () => {
        const L = await import('leaflet');
        setIcon(L.icon(iconProps));
      }
      loadIcon();
    },
    [iconProps]
  );

  // waiting for icon to be loaded before rendering
  return (!!iconProps && !icon) ? null : (
    <LMarker
      {...props}
      icon={icon}
      ref={forwardedRef}
    />
  );
};

// MapComponents.jsx
// ...
const LazyMarker = dynamic(() => import('./MapLazyComponents').then((m) => m.Marker), { ssr: false });
export const Marker = forwardRef((props, ref) => (
  <LazyMarker {...props} forwardedRef={ref} />
));

// Map.jsx
// ...
import { MapContainer, TileLayer, ZoomControl, Marker } from './MapComponents.jsx';

import CustomIcon from '../public/custom-icon.svg';

const Map = (props) => {
  const mapRef = useRef(null);
  const markerRef = useRef(null);
  return (
    <MapContainer
      ref={mapRef}
      touchZoom={false}
      zoomControl={false}
      style={{ height: '400px', zIndex: '0!important' }}
    >
      <TileLayer url="..." attribution="..." style={{ zIndex: '0!important' }} />
      <ZoomControl position="topright" style={{ zIndex: '10!important' }} />
      <Marker
        ref={markerRef}
        icon={{
          iconUrl: CustomIcon.src,
          iconAnchor: [16,32],
          iconSize: [32,32]
        }}
        style={{ zIndex: '1!important' }}
      />
    </MapContainer>
  );
};
//...

Handling map events

For marker events, you can already pass the eventHandlers property and it'll work. But to handle map events, it can not be done on the <MapContainer> component, you need to use the useMapEvents() hook from React Leaflet in a child component.

Same here, we'll need to wrap it, and we'll do it within a custom <MapConsumer> element to simplify things:

// MapLazyComponents.jsx
//...
import { useMapEvents } from 'react-leaflet/hooks';
export const MapConsumer = ({ eventsHandler }) => {
  useMapEvents(eventsHandler);
  return null;
};

// MapComponents.jsx
//...
export const MapConsumer = dynamic(
  () => import('./MapLazyComponents').then((m) => m.MapConsumer),
  { ssr: false }
);

So in you Map.jsx file, you're now able to add <MapConsumer> in <MapContainer>:

// Map.jsx
//...
const Map = (props) => {
  const mapRef = useRef(null);
  const markerRef = useRef(null);

  const mapHandlers = useMemo(
    () => ({
      click(e) {
        // center view on the coordinates of the click
        // `this` is the Leaflet map object
        this.setView([e.latlng.lat, e.latlng.lng]);
      },
    }),
    []
  );

  return (
    <MapContainer
      ref={mapRef}
      touchZoom={false}
      zoomControl={false}
      style={{ height: '400px', zIndex: '0!important' }}
    >
      <TileLayer url="..." attribution="..." style={{ zIndex: '0!important' }} />
      <ZoomControl position="topright" style={{ zIndex: '10!important' }} />
      <MapConsumer
        eventsHandler={mapHandlers}
      />
      <Marker
        ref={markerRef}
        icon={{
          iconUrl: CustomIcon.src,
          iconAnchor: [16,32],
          iconSize: [32,32]
        }}
        style={{ zIndex: '1!important' }}
      />
    </MapContainer>
  );
};

A few states and CSS later, here's my result:

So we've seen how to:

lazy load components with next/dynamic,
make ref work with lazy-loaded components,
dynamically load leaflet to access its methods like L.Icon,
wrap react-leaflet custom hooks to handle events.

Adapting these tricks should cover most of your edge cases. I hope breaking down into these specific use-cases will help you work better with React Leaflet on NextJS!

And of course, if you need a reverse geocoding API to get coordinates from an address, have a look at PlaceKit.io :)!

DEV Community: PlaceKit

How to use DEV.to as a CMS to make a blog with NextJS

1. Preparing NextJS

Dependencies

Environment variables

Pages structure with /pages router

Pages structure with /app router

2. Preparing Methods

3. Listing articles

/pages router

/app router

Link articles

4. Article page

/pages router, SSR mode

/pages router, SSG mode

/app router

Adding anchors and code snippets syntax highlighting

5. Updating canonical for SEO

6. Bonus: handling pagination

Folder structure

Adding pagination data to articles list

/pages router, SSR mode

/pages router, SSG mode

/app router

Google Maps is always right… right?

Table Of Contents

A bit of context

Navigating state boundaries

Not so close to a state boundary

The Wild Turkey Run

Off-course: far beyond state boundaries

An interstate flight is cheaper than Google Maps API pricing ✈️

Lost in address translation

Wrapping up: navigating through imperfect data

Introducing Live Patching

Motivation

How does it work

Using the admin panel

Using the API

Adding a missing location

Fixing an existing location

Listing patch records

Retrieving a patch record

Updating a patch record

Delete a patch record

Making React-Leaflet work with NextJS

Passing ref

Organizing your components

Using custom Marker icons

Handling map events

Pages structure with `/pages` router

Pages structure with `/app` router

`/pages` router

`/app` router

`/pages` router, SSR mode

`/pages` router, SSG mode

`/app` router

`/pages` router, SSR mode

`/pages` router, SSG mode

`/app` router

Passing `ref`