MARKETING

The Moz Links API: An Introduction

Published

11 months ago

May 30, 2023

What exactly IS an API? They’re those things that you copy and paste long strange codes into Screaming Frog for links data on a Site Crawl, right?

I’m here to tell you there’s so much more to them than that – if you’re willing to take just a few little steps. But first, some basics.

What’s an API?

API stands for “application programming interface”, and it’s just the way of… using a thing. Everything has an API. The web is a giant API that takes URLs as input and returns pages.

But special data services like the Moz Links API have their own set of rules. These rules vary from service to service and can be a major stumbling block for people taking the next step.

When Screaming Frog gives you the extra links columns in a crawl, it’s using the Moz Links API, but you can have this capability anywhere. For example, all that tedious manual stuff you do in spreadsheet environments can be automated from data-pull to formatting and emailing a report.

If you take this next step, you can be more efficient than your competitors, designing and delivering your own SEO services instead of relying upon, paying for, and being limited by the next proprietary product integration.

GET vs. POST

Most APIs you’ll encounter use the same data transport mechanism as the web. That means there’s a URL involved just like a website. Don’t get scared! It’s easier than you think. In many ways, using an API is just like using a website.

As with loading web pages, the request may be in one of two places: the URL itself, or in the body of the request. The URL is called the “endpoint” and the often invisibly submitted extra part of the request is called the “payload” or “data”. When the data is in the URL, it’s called a “query string” and indicates the “GET” method is used. You see this all the time when you search:

https://www.google.com/search?q=moz+links+api <-- GET method

When the data of the request is hidden, it’s called a “POST” request. You see this when you submit a form on the web and the submitted data does not show on the URL. When you hit the back button after such a POST, browsers usually warn you against double-submits. The reason the POST method is often used is that you can fit a lot more in the request using the POST method than the GET method. URLs would get very long otherwise. The Moz Links API uses the POST method.

Making requests

A web browser is what traditionally makes requests of websites for web pages. The browser is a type of software known as a client. Clients are what make requests of services. More than just browsers can make requests. The ability to make client web requests is often built into programming languages like Python, or can be broken out as a standalone tool. The most popular tools for making requests outside a browser are curl and wget.

We are discussing Python here. Python has a built-in library called URLLIB, but it’s designed to handle so many different types of requests that it’s a bit of a pain to use. There are other libraries that are more specialized for making requests of APIs. The most popular for Python is called requests. It’s so popular that it’s used for almost every Python API tutorial you’ll find on the web. So I will use it too. This is what “hitting” the Moz Links API looks like:

response = requests.post(endpoint, data=json_string, auth=auth_tuple)

Given that everything was set up correctly (more on that soon), this will produce the following output:

{'next_token': 'JYkQVg4s9ak8iRBWDiz1qTyguYswnj035nqrQ1oIbW96IGJsb2dZgGzDeAM7Rw==',
 'results': [{'anchor_text': 'moz',
              'external_pages': 7162,
              'external_root_domains': 2026}]}

This is JSON data. It’s contained within the response object that was returned from the API. It’s not on the drive or in a file. It’s in memory. So long as it’s in memory, you can do stuff with it (often just saving it to a file).

If you wanted to grab a piece of data within such a response, you could refer to it like this:

response['results'][0]['external_pages']

This says: “Give me the first item in the results list, and then give me the external_pages value from that item.” The result would be 7162.

NOTE: If you’re actually following along executing code, the above line won’t work alone. There’s a certain amount of setup we’ll do shortly, including installing the requests library and setting up a few variables. But this is the basic idea.

JSON

JSON stands for JavaScript Object Notation. It’s a way of representing data in a way that’s easy for humans to read and write. It’s also easy for computers to read and write. It’s a very common data format for APIs that has somewhat taken over the world since the older ways were too difficult for most people to use. Some people might call this part of the “restful” API movement, but the much more difficult XML format is also considered “restful” and everyone seems to have their own interpretation. Consequently, I find it best to just focus on JSON and how it gets in and out of Python.

Python dictionaries

I lied to you. I said that the data structure you were looking at above was JSON. Technically it’s really a Python dictionary or dict datatype object. It’s a special kind of object in Python that’s designed to hold key/value pairs. The keys are strings and the values can be any type of object. The keys are like the column names in a spreadsheet. The values are like the cells in the spreadsheet. In this way, you can think of a Python dict as a JSON object. For example here’s creating a dict in Python:

my_dict = {
    "name": "Mike",
    "age": 52,
    "city": "New York"
}

And here is the equivalent in JavaScript:

var my_json = {
    "name": "Mike",
    "age": 52,
    "city": "New York"
}

Pretty much the same thing, right? Look closely. Key-names and string values get double-quotes. Numbers don’t. These rules apply consistently between JSON and Python dicts. So as you might imagine, it’s easy for JSON data to flow in and out of Python. This is a great gift that has made modern API-work highly accessible to the beginner through a tool that has revolutionized the field of data science and is making inroads into marketing, Jupyter Notebooks.

Flattening data

But beware! As data flows between systems, it’s not uncommon for the data to subtly change. For example, the JSON data above might be converted to a string. Strings might look exactly like JSON, but they’re not. They’re just a bunch of characters. Sometimes you’ll hear it called “serializing”, or “flattening”. It’s a subtle point, but worth understanding as it will help with one of the largest stumbling blocks with the Moz Links (and most JSON) APIs.

Objects have APIs

Actual JSON or dict objects have their own little APIs for accessing the data inside of them. The ability to use these JSON and dict APIs goes away when the data is flattened into a string, but it will travel between systems more easily, and when it arrives at the other end, it will be “deserialized” and the API will come back on the other system.

Data flowing between systems

This is the concept of portable, interoperable data. Back when it was called Electronic Data Interchange (or EDI), it was a very big deal. Then along came the web and then XML and then JSON and now it’s just a normal part of doing business.

If you’re in Python and you want to convert a dict to a flattened JSON string, you do the following:

import json

my_dict = {
    "name": "Mike",
    "age": 52,
    "city": "New York"
}

json_string = json.dumps(my_dict)

…which would produce the following output:

'{"name": "Mike", "age": 52, "city": "New York"}'

This looks almost the same as the original dict, but if you look closely you can see that single-quotes are used around the entire thing. Another obvious difference is that you can line-wrap real structured data for readability without any ill effect. You can’t do it so easily with strings. That’s why it’s presented all on one line in the above snippet.

Such stringifying processes are done when passing data between different systems because they are not always compatible. Normal text strings on the other hand are compatible with almost everything and can be passed on web-requests with ease. Such flattened strings of JSON data are frequently referred to as the request.

Anatomy of a request

Again, here’s the example request we made above:

response = requests.post(endpoint, data=json_string, auth=auth_tuple)

Now that you understand what the variable name json_string is telling you about its contents, you shouldn’t be surprised to see this is how we populate that variable:

 data_dict = {
    "target": "moz.com/blog",
    "scope": "page",
    "limit": 1
}

json_string = json.dumps(data_dict)

…and the contents of json_string looks like this:

'{"target": "moz.com/blog", "scope": "page", "limit": 1}'

This is one of my key discoveries in learning the Moz Links API. This is in common with countless other APIs out there but trips me up every time because it’s so much more convenient to work with structured dicts than flattened strings. However, most APIs expect the data to be a string for portability between systems, so we have to convert it at the last moment before the actual API-call occurs.

Pythonic loads and dumps

Now you may be wondering in that above example, what a dump is doing in the middle of the code. The json.dumps() function is called a “dumper” because it takes a Python object and dumps it into a string. The json.loads() function is called a “loader” because it takes a string and loads it into a Python object.

The reason for what appear to be singular and plural options are actually binary and string options. If your data is binary, you use json.load() and json.dump(). If your data is a string, you use json.loads() and json.dumps(). The s stands for string. Leaving the s off means binary.

Don’t let anybody tell you Python is perfect. It’s just that its rough edges are not excessively objectionable.

Assignment vs. equality

For those of you completely new to Python or programming in general, what we’re doing when we hit the API is called an assignment. The result of requests.post() is being assigned to the variable named response.

response = requests.post(endpoint, data=json_string, auth=auth_tuple)

We are using the = sign to assign the value of the right side of the equation to the variable on the left side of the equation. The variable response is now a reference to the object that was returned from the API. Assignment is different from equality. The == sign is used for equality.

# This is assignment:
a = 1  # a is now equal to 1

# This is equality:
a == 1  # True, but relies that the above line has been executed

The POST method

response = requests.post(endpoint, data=json_string, auth=auth_tuple)

The requests library has a function called post() that takes 3 arguments. The first argument is the URL of the endpoint. The second argument is the data to send to the endpoint. The third argument is the authentication information to send to the endpoint.

Keyword parameters and their arguments

You may notice that some of the arguments to the post() function have names. Names are set equal to values using the = sign. Here’s how Python functions get defined. The first argument is positional both because it comes first and also because there’s no keyword. Keyworded arguments come after position-dependent arguments. Trust me, it all makes sense after a while. We all start to think like Guido van Rossum.

def arbitrary_function(argument1, name=argument2):
    # do stuff

The name in the above example is called a “keyword” and the values that come in on those locations are called “arguments”. Now arguments are assigned to variable names right in the function definition, so you can refer to either argument1 or argument2 anywhere inside this function. If you’d like to learn more about the rules of Python functions, you can read about them here.

Setting up the request

Okay, so let’s let you do everything necessary for that success assured moment. We’ve been showing the basic request:

response = requests.post(endpoint, data=json_string, auth=auth_tuple)

…but we haven’t shown everything that goes into it. Let’s do that now. If you’re following along and don’t have the requests library installed, you can do so with the following command from the same terminal environment from which you run Python:

pip install requests

Often times Jupyter will have the requests library installed already, but in case it doesn’t, you can install it with the following command from inside a Notebook cell:

!pip install requests

And now we can put it all together. There’s only a few things here that are new. The most important is how we’re taking 2 different variables and combining them into a single variable called AUTH_TUPLE. You will have to get your own ACCESSID and SECRETKEY from the Moz.com website.

The API expects these two values to be passed as a Python data structure called a tuple. A tuple is a list of values that don’t change. I find it interesting that requests.post() expects flattened strings for the data parameter, but expects a tuple for the auth parameter. I suppose it makes sense, but these are the subtle things to understand when working with APIs.

Here’s the full code:

import json
import pprint
import requests

# Set Constants
ACCESSID = "mozscape-1234567890"  # Replace with your access ID
SECRETKEY = "1234567890abcdef1234567890abcdef"  # Replace with your secret key
AUTH_TUPLE = (ACCESSID, SECRETKEY)

# Set Variables
endpoint = "https://lsapi.seomoz.com/v2/anchor_text"
data_dict = {"target": "moz.com/blog", "scope": "page", "limit": 1}
json_string = json.dumps(data_dict)

# Make the Request
response = requests.post(endpoint, data=json_string, auth=AUTH_TUPLE)

# Print the Response
pprint(response.json())

…which outputs:

{'next_token': 'JYkQVg4s9ak8iRBWDiz1qTyguYswnj035nqrQ1oIbW96IGJsb2dZgGzDeAM7Rw==',
 'results': [{'anchor_text': 'moz',
              'external_pages': 7162,
              'external_root_domains': 2026}]}

Using all upper case for the AUTH_TUPLE variable is a convention many use in Python to indicate that the variable is a constant. It’s not a requirement, but it’s a good idea to follow conventions when you can.

You may notice that I didn’t use all uppercase for the endpoint variable. That’s because the anchor_text endpoint is not a constant. There are a number of different endpoints that can take its place depending on what sort of lookup we wanted to do. The choices are:

anchor_text
final_redirect
global_top_pages
global_top_root_domains
index_metadata
link_intersect
link_status
linking_root_domains
links
top_pages
url_metrics
usage_data

And that leads into the Jupyter Notebook that I prepared on this topic located here on Github. With this Notebook you can extend the example I gave here to any of the 12 available endpoints to create a variety of useful deliverables, which will be the subject of articles to follow.

Related Topics:api Introduction links moz seo

Up Next

Mnemonic Content Strategy Framework Can Spark Conversations

Don't Miss

What Businesses Get Wrong About Content Marketing in 2023 [Expert Tips]

MARKETING

Generative Engine Optimization Framework Introduced in New Research

Published

17 hours ago

May 2, 2024

Entireweb News Bot

Generative Engine Optimization Framework Introduced in New Research

There are several AI chatbot-like features available in the current search engines, including Bing Copilot, Google, Bard, and Gemini. They help to optimize the content visibility in the search results with the help of an AI-powered Search engine known as a Generative engine or AI Search.

A traditional search engine like Bing, Google, or Yahoo ranks and displays information in the SERPs based on the search terms a user inputs. 🔎

The generative engine, on the other hand, generates comprehensive, accurate, and relevant results and information with the help of Generative AI or Large Language Models (LLMs) such as chatGPT, Gemini, and Claude. They understand and integrate information from various sources for the user’s queries.

In this blog, We will discuss the GEO that is introduced in the new research, its framework, and how it can change traditional Search engine optimization (SEO) practices and optimize content for visibility.

The Key Components of the GEO Framework and How They Transform Traditional SEO Practices

GEO is described in the research paper as: “A novel paradigm to aid content creators in improving the visibility of their content in Generative Engine responses through a black-box optimization framework for optimizing and defining visibility metrics. We facilitate systematic evaluation in this new paradigm by introducing GEO-bench, a benchmark of diverse user queries across multiple domains, coupled with sources required to answer these queries.”

Traditional SEO depends upon the keyword volume, difficulty, and optimization for the specific search terms, which focus less on an interpretation relationship between the concepts of keywords or user queries. SEO practices prioritize text-based source content over other sources of content format where regular updating of fresh content is not a primary focus. Also, metrics like impression and click rates affect ranking system results in traditional methods.

GEO encourages detailed information over just the keyword, addressing the related main queries by creating depth content and potential subtopics with the understanding of concept and relationship, encouraging the other formats, such as visual, audio, and images, not just text-based. Moreover, it emphasizes the latest updated content information with continuous accuracy and relevance to provide the most accurate and up-to-date details.

The Impact of Introducing GEO on Website Ranking and Content Relevancy

A generative engine relies on traditional SEO practices like user intent and algorithms for ranking to a degree, such as keyword stuffing. Although it focuses on keywords, it tries to find connections and meanings beyond the keywords in order to create high-quality content.

GEO doesn’t directly indicate the web visibility or page ranking in the Search Engine Result Page. However, it can optimize the overall website visibility and indirectly drive user traffic to your websites through generated responsive data and information.

GEO-optimized content provides the AI Search or a Large Language Model (LLM) with reliable and completely detailed information, enabling them to generate the most accurate and relevant information for responses to user questions or inputs.

These AI-powered engines can deliver a vibrant user experience using optimized content for user engagement and interactive experiences. Furthermore, It also builds trust with a user as it relies on renowned and credible sources, which enhances the effectiveness and reliability of the generated response data and provides synthesizing information.

Comparison with Existing SEO Models: Why GEO Stands Out in Enhancing Search Engine Performance

GEO utilizes auto-generative algorithms for content generation based on predetermined objectives and standards where generated content can cover a broader range of keywords and related topics in various formats like image and visual.

A generative search engine uses modern optimization techniques that involve cognitive SEO, NLP (natural language processing), and structured data markup to maintain and improve content leverage, relevancy, and search engine visibility. In addition, it introduces new methods for determining citations’ importance and website visibility, as well as improving user-centric content by using impression metrics.

Traditional SEO models rely upon and use specific keywords to optimize and rank manually in search results. It uses traditional optimization techniques like link building, meta tags, and URLs.

In traditional search optimization, content creation and optimization can be slow and have low content scalability compared to AI-powered, requiring manual effort for generation and optimization. Constant monitoring and adaptation to platform algorithms are needed to produce the latest and updated information for dynamic user behavior.

Both are equally responsible for improving the brand or website’s online visibility; traditional SEO models require the manual touch for content creation and optimization. GEO tends to use generative responses automatically for content generation as per user queries, making it more effective for user-centric content creation, optimization, and stability in related topics or keywords.

9 Test research findings to improve the website content in GEO

The researchers from Princeton University, Georgia Tech, Allen Institute for AI, and IIT Delhi tested nine various GEO approaches to improve site content for generative engines. Techniques that have been tried and tested over 10,000 search queries, nine optimization strategies were tested on something that “closely resembles the design of BingChat”:

1714643800 803 Generative Engine Optimization Framework Introduced in New Research

Authoritative: The content was altered to be more compelling while conveying definitive claims.
Keyword Stuffing: More keywords were added to match the query.
Statistics Addition: Instead of a qualitative conversation, quantitative statistics were included.
Sources: Relevant citations have been added. Like quotes statistics
Quotation Addition: Quotations from reliable sources have been included.
Easy-to-understand: Simplified the language.
Fluency Optimisation: Improved fluency.
Unique Words: Used in the text whenever possible.
Technical terms: Technical terms have been incorporated into the content.

The data set for search queries was obtained from Google, Microsoft Bing, and Perplexity. Sources include AI Discover, GPT-4, and others.

So, focus on creating detailed and comprehensive blogs or articles by defining the relation and highlighting the context for deeper meaning. Utilize the various formats for content creation to enrich information and diversify the learning perspective.

Also, update your content with the latest information and trends to maintain regular effectiveness and relevancy in the generative engines.

Conclusion:

In the end, Generative Engine Optimization (GEO) provides a more automated, scalable, and adaptive method of content creation and optimization than traditional Search Engine Optimization (SEO) approaches, which need manual and constant work for the optimization and ranking. Compared to traditional search engines, generative engines give instant and detailed personalized information to users’ queries for improved engagement.

Conventional SEO uses metrics like impression, session duration, and click-through rate (CTR), whereas GEO proposes new metrics to measure the relevance and visibility of citations within generative engine responses, making users eliminate the need to visit individual websites for information as it generates the responses on users queries from the reliable, relevant, and various sources.

AI-powered search optimization is still developing and becoming popular since most users and business owners are using generative AI as their source of information and improved visibility with universally applicable diverse content formats.

MARKETING

How To Develop a Great Creative Brief and Get On-Target Content

Published

2 days ago

May 1, 2024

Entireweb News Bot

How To Develop a Great Creative Brief and Get On-Target Content

Every editor knows what it feels like to sit exasperated in front of the computer, screaming internally, “It would have been easier if I’d done it myself.”

If your role involves commissioning and approving content, you know that sinking feeling: Ten seconds into reviewing a piece, it’s obvious the creator hasn’t understood (or never bothered to listen to) a damn thing you told them. As you go deeper, your fingertips switch gears from polite tapping to a digital Riverdance as your annoyance spews onto the keyboard. We’ve all been there. It’s why we drink. Or do yoga. Or practice voodoo.

In truth, even your best writer, designer, or audiovisual content creator can turn in a bad job. Maybe they had an off day. Perhaps they rushed to meet a deadline. Or maybe they just didn’t understand the brief.

The first two excuses go to the content creator’s professionalism. You’re allowed to get grumpy about that. But if your content creator didn’t understand the brief, then you, as the editor, are at least partly to blame.

Taking the time to create a thorough but concise brief is the single greatest investment you can make in your work efficiency and sanity. The contrast in emotions when a perfectly constructed piece of content lands in your inbox could not be starker. It’s like the sun has burst through the clouds, someone has released a dozen white doves, and that orchestra that follows you around has started playing the lovely bit from Madame Butterfly — all at once.

Here’s what a good brief does:

It clearly and concisely sets out your expectations (so be specific).
It focuses the content creator’s mind on the areas of most importance.
It encourages the content creator to do a thorough job rather than an “it’ll-do” job.
It results in more accurate and more effective content (content that hits the mark).
It saves hours of unnecessary labor and stress in the editing process.
It can make all the difference between profit and loss.

Arming content creators with a thorough brief gives them the best possible chance of at least creating something fit for purpose — even if it’s not quite how you would have done it. Give them too little information, and there’s almost no hope they’ll deliver what you need.

On the flip side, overloading your content creators with more information than they need can be counterproductive. I know a writer who was given a 65-page sales deck to read as background for a 500-word blog post. Do that, and you risk several things happening:

It’s not worth the content creator’s time reading it, so they don’t.
Even if they do read it, you risk them missing out on the key points.
They’ll charge you a fortune because they’re losing money doing that amount of preparation.
They’re never going to work with you again.

There’s a balance to strike.

There’s a balance to be struck.

Knowing how to give useful and concise briefs is something I’ve learned the hard way over 20 years as a journalist and editor. What follows is some of what I’ve found works well. Some of this might read like I’m teaching grandma to suck eggs, but I’m surprised how many of these points often get forgotten.

Who is the client?

Provide your content creator with a half- or one-page summary of the business:

Who it is
What it does
Whom it services
What its story is
Details about any relevant products and services

Include the elevator pitch and other key messaging so your content creator understands how the company positions itself and what kind of language to weave into the piece.

Who is the audience?

Include a paragraph or two about the intended audience. If a company has more than one audience (for example, a recruitment company might have job candidates and recruiters), then be specific. Even a sentence will do, but don’t leave your content creator guessing. They need to know who the content is for.

What needs to be known?

This is the bit where you tell your content creator what you want them to create. Be sure to include three things:

The purpose of the piece
The angle to lead with
The message the audience should leave with

I find it helps to provide links to relevant background information if you have it available, particularly if the information inspired or contributed to the content idea, rather than rely on content creators to find their own. It can be frustrating when their research doesn’t match or is inferior to your own.

How does the brand communicate?

Include any information the content creators need to ensure that they’re communicating in an authentic voice of the brand.

Tone of voice: The easiest way to provide guidance on tone of voice is to provide one or two examples that demonstrate it well. It’s much easier for your content creators to mimic a specific example they’ve seen, read, or heard than it is to interpret vague terms like “formal,” “casual,” or “informative but friendly.”
Style guide: Giving your content creator a style guide can save you a lot of tinkering. This is essential for visuals but also important for written content if you don’t want to spend a lot of time changing “%” to “percent” or uncapitalizing job titles. Summarize the key points or most common errors.
Examples: Examples aren’t just good for tone of voice; they’re also handy for layout and design to demonstrate how you expect a piece of content to be submitted. This is especially handy if your template includes social media posts, meta descriptions, and so on.

All the elements in a documented brief

Here are nine basic things every single brief requires:

Title: What are we calling this thing? (A working title is fine so that everyone knows how to refer to this project.)
Client: Who is it for, and what do they do?
Deadline: When is the final content due?
The brief itself: What is the angle, the message, and the editorial purpose of the content? Include here who the audience is.
Specifications: What is the word count, format, aspect ratio, or run time?
Submission: How and where should the content be filed? To whom?
Contact information: Who is the commissioning editor, the client (if appropriate), and the talent?
Resources: What blogging template, style guide, key messaging, access to image libraries, and other elements are required to create and deliver the content?
Fee: What is the agreed price/rate? Not everyone includes this in the brief, but it should be included if appropriate.

Depending on your business or the kind of content involved, you might have other important information to include here, too. Put it all in a template and make it the front page of your brief.

Prepare your briefs early

It’s entirely possible you’re reading this, screaming internally, “By the time I’ve done all that, I could have written the damn thing myself.”

But much of this information doesn’t change. Well in advance, you can document the background about a company, its audience, and how it speaks doesn’t change. You can pull all those resources into a one- or two-page document, add some high-quality previous examples, throw in the templates they’ll need, and bam! You’ve created a short, useful briefing package you can provide to any new content creator whenever it is needed. You can do this well ahead of time.

I expect these tips will save you a lot of internal screaming in the future. Not to mention drink, yoga, and voodoo.

This is an update of a January 2019 CCO article.

Get more advice from Chief Content Officer, a monthly publication for content leaders. Subscribe today to get it in your inbox.

HANDPICKED RELATED CONTENT:

Cover image by Joseph Kalinowski/Content Marketing Institute